loopable / api /tool_groups /requests.py
fsanyoto's picture
Deploy AIOS web (React glide grid + FastAPI slice)
868b75a verified
Raw History Blame
16.5 kB
"""C2 request handlers with authenticated attribution and C4 task storage."""
from core import external_access, external_oauth, external_tools, perm_scope
from deps import Session
import agent_directory
import agent_inbox
import tickets
def _identity(ctx, *, write=False):
"""Resolve identity from the verified context and current credential registry only."""
if not isinstance(ctx, external_tools.ToolContext) or not isinstance(ctx.session, Session):
raise PermissionError("Sign in with an identified AI connection.")
session = ctx.session
claims = session.claims or {}
kind, credential = claims.get("external_auth_type"), claims.get("external_credential_id")
if (claims.get("external") is not True or kind not in ("oauth", "api_key") or not credential
or claims.get("u") != session.uname or claims.get("t") != session.tenant
or session.tenant != session.runtime.key):
raise PermissionError("Sign in with an identified AI connection.")
name, principal = tickets._principal(session.runtime, session.uname)
refusal = perm_scope.ai_apps_refusal(principal, session.runtime)
if refusal:
raise PermissionError(refusal)
now = tickets._utc()
if claims.get("exp") is not None and float(claims["exp"]) <= now.timestamp():
raise PermissionError("This connection has expired. Sign in again.")
if kind == "oauth":
label = external_oauth.label_for(session.runtime, credential)
book = external_oauth._book(session.runtime)
record = book["grants"].get(credential) or {}
client = book["clients"].get(record.get("client_id")) or {}
if (not claims.get("external_client_id") or record.get("client_id") != claims["external_client_id"]
or client.get("username") != name or client.get("tenant") != session.tenant
or record.get("disconnected_at") or client.get("revoked_at")):
raise PermissionError("This AI connection is unavailable. Sign in again.")
if float(record.get("access_expires_at") or 0) <= now.timestamp():
raise PermissionError("This AI connection has expired. Sign in again.")
# OAuth's live effective scope is supplied by require_external_session.
access, databases = external_access.scope_of({
"access": claims.get("external_access"), "databases": claims.get("external_databases")})
else:
if credential != claims.get("external_key_id"):
raise PermissionError("Sign in with an identified AI connection.")
label = external_access.label_for(session.runtime, credential)
record = external_access._book(session.runtime).get(credential) or {}
if record.get("expires_at") and tickets._utc(record["expires_at"]) <= now:
raise PermissionError("This key has expired. Sign in again.")
access, databases = external_access.scope_of(record)
if record.get("username") != name or record.get("tenant") != session.tenant:
raise PermissionError("This connection belongs to another person or workspace.")
from routes_external import _contains_credential
if any(_contains_credential(value) for value in (name, principal.get("name"), label, ctx.actor_name)):
raise PermissionError("Person names and AI labels must not contain credential values.")
if write and (not external_access.may_write(claims.get("external_access"))
or not external_access.may_write(access)):
raise PermissionError("This connection is read only. Allow writes before changing requests.")
return name, tickets._text(label), f"{kind}:{credential}", databases
def _source_scope(ctx, source, databases):
"""Check credential scope and the current database wall beside attribution's source admission."""
if source is None:
return
database = source["database"]
if (not external_access.database_allowed(databases, database)
or not external_access.database_allowed(ctx.session.claims.get("external_databases"), database)):
raise PermissionError("The source database is outside this connection's scope.")
ctx.describe_database(database)
def _send_source_admission(ctx, source, databases):
"""Admit sends through both credential scope and full source-data access."""
_source_scope(ctx, source, databases)
if source is None:
return
prepared = tickets._prepare_request_source(ctx.session.runtime, ctx.session.uname, source)
if ctx.session.uname not in tickets.audience(ctx.session.runtime, prepared):
raise PermissionError("You cannot see all the fields and rows this request needs.")
def _arguments(args, allowed, required=()):
if not isinstance(args, dict) or set(args) - set(allowed) or any(key not in args for key in required):
raise ValueError("Use the arguments listed for this request action.")
def send(ctx, args):
"""Send without confirmation after source, recipient and connection admission."""
_arguments(args, ("to", "kind", "title", "body", "source"), ("to", "kind", "title", "body"))
name, label, connection, databases = _identity(ctx, write=True)
if (not isinstance(args["to"], list) or not args["to"]
or any(not isinstance(person, str) or not person.strip() for person in args["to"])):
raise ValueError("Choose at least one recipient by username.")
if len(args["to"]) > tickets.MAX_REQUEST_RECIPIENTS:
raise ValueError(f"Send a request to at most {tickets.MAX_REQUEST_RECIPIENTS} people. Split this request into smaller groups.")
if any(not isinstance(args[key], str) for key in ("kind", "title", "body")):
raise ValueError("The kind, title and body must be text.")
source = tickets.request_source(args.get("source"))
_send_source_admission(ctx, source, databases)
return tickets.send_external_request(ctx.session.runtime, name, args["to"], args["kind"],
args["title"], args["body"], source, via=label, connection=connection)
def inbox(ctx, args):
"""Count all open tasks and return their twenty newest safe attribution projections."""
_arguments(args, ())
name, _label, _connection, databases = _identity(ctx)
return tickets.request_inbox(ctx.session.runtime, name,
source_check=lambda source: _source_scope(ctx, source, databases))
def list_team(ctx, args):
"""List teammates through a strict name and activity whitelist."""
_arguments(args, ())
name, _label, _connection, _databases = _identity(ctx)
return {"people": [{"name": str(rec.get("name") or uname),
"lastActive": rec.get("last_active") if isinstance(rec.get("last_active"), str) else None}
for uname, rec in agent_directory._accounts(ctx.session) if uname != name]}
# Source-less text must come from a closed vocabulary, never from model-authored data.
_SOCIAL_MESSAGES = ("Hello.", "Hi.", "Are you available?", "Can we talk?", "Can you help?", "Thank you.")
def send_message(ctx, args):
"""Deliver a question or an authorization-only change request through the shared request transport."""
_arguments(args, ("to", "kind", "text", "source", "change"), ("to", "kind", "text"))
_name, _label, _connection, _databases = _identity(ctx, write=True)
if not isinstance(args["to"], str) or not args["to"].strip():
raise ValueError("Choose one teammate by name.")
if args["kind"] not in ("question", "change") or not isinstance(args["text"], str):
raise ValueError("Choose a question or a proposed change with one line of text.")
text = agent_inbox._text(args["text"])
source = tickets.request_source(args.get("source"))
if source is not None:
_arguments(args["source"], ("database", "record"), ("database",))
if args["kind"] == "change":
if source is None or not isinstance(args.get("change"), str):
raise ValueError("A proposed change needs a readable source and a change description.")
if source["database"] == "applications":
raise ValueError("Team change proposals need a data source. App sharing uses its separate human approval flow.")
change = agent_inbox._text(args["change"])
title, kind = agent_inbox.TEAM_CHANGE_TITLE, "approval"
text = f"{agent_inbox.TEAM_CHANGE_PREFIX}{change}\nQuestion: {text}\n{agent_inbox.TEAM_AUTHORIZATION_NOTE}"
else:
if "change" in args:
raise ValueError("Use kind change to propose a change.")
if source is None:
social = {value.casefold().rstrip(".!?"): value for value in _SOCIAL_MESSAGES}
key = text.casefold().rstrip(".!?")
if key not in social:
raise ValueError("Without a source, use a listed greeting or question. Other text needs a readable source.")
text = social[key]
title, kind = "A teammate has a question.", "question"
recipient, _record = agent_inbox._recipient(ctx.session, args["to"])
return send(ctx, {"to": [recipient], "kind": kind, "title": title, "body": text, "source": source})
def check_inbox(ctx, args):
"""Read the shared inbox with current source and credential access."""
return inbox(ctx, args)
def _approval_access(ctx, args):
name, _label, _connection, databases = _identity(ctx)
agent_inbox.team_approval(ctx.session.runtime, args["id"], name,
source_check=lambda source: _source_scope(ctx, source, databases))
return True
def ask_user(ctx, args):
"""Preview the recipient's explicit decision, then record authorization without executing a target write."""
_arguments(args, ("id", "decision"), ("id", "decision"))
_name, _label, _connection, databases = _identity(ctx, write=True)
if args["decision"] not in ("Approve", "Deny"):
raise ValueError("Ask the recipient to choose Approve or Deny.")
from routes_external import _ConfirmationRuntime, _PreviewRuntime
if not isinstance(ctx.session.runtime, (_PreviewRuntime, _ConfirmationRuntime)):
raise PermissionError("Show the recipient a preview and confirm their decision before saving it.")
return agent_inbox.decide_request(ctx.session, args["id"], args["decision"], authorization_only=True,
source_check=lambda source: _source_scope(ctx, source, databases))
def _change(ctx, args, *, complete=False):
allowed = ("id",) if complete else ("id", "body", "state")
_arguments(args, allowed, ("id",) if complete else ("id", "body"))
name, _label, _connection, databases = _identity(ctx, write=True)
source_check = lambda source: _source_scope(ctx, source, databases)
task = tickets.get_request_attribution(ctx.session.runtime, args["id"], name, source_check=source_check)
if not task["sourceVisible"]:
raise PermissionError("You cannot see the source data this request needs.")
if task["kind"] == "approval" and task["title"] == agent_inbox.TEAM_CHANGE_TITLE:
raise PermissionError("Ask the recipient to choose Approve or Deny through requests.ask_user.")
state = "completed" if complete else args.get("state", "working")
if not complete and (state not in ("working", "input-required", "rejected")
or not isinstance(args["body"], str) or not args["body"].strip()):
raise ValueError("Give an answer and choose working, input-required or rejected.")
tickets.set_request_state(ctx.session.runtime, args["id"], name, state, args.get("body"))
return tickets.get_request_attribution(ctx.session.runtime, args["id"], name, source_check=source_check)
def answer(ctx, args):
"""Save a recipient's answer without invoking the human access-grant action."""
return _change(ctx, args)
def complete(ctx, args):
"""Complete a recipient's task through the normal confirmed write path."""
return _change(ctx, args, complete=True)
def _receipt_access(ctx, args):
"""Read current task and source access, including completed tasks, without invoking a writer."""
name, _label, _connection, databases = _identity(ctx)
task = tickets.get_request_attribution(
ctx.session.runtime, args["id"], name,
source_check=lambda source: _source_scope(ctx, source, databases))
if not task["sourceVisible"]:
raise PermissionError("You cannot see the source data this request needs.")
return True
def _schema(properties, required=()):
return {"type": "object", "properties": properties, "required": list(required), "additionalProperties": False}
GROUP = {
"name": "requests", "title": "Requests",
"guide": "Use list_team for teammates' names and lastActive times only. Use send_message for a question or proposed change. "
"Use check_inbox for received requests and ask_user to record the recipient's explicit Approve or Deny after human confirmation. "
"Approval authorizes the recipient AI only. It executes no target write and grants no access. Later writes need normal permissions and confirmation. "
"Send a request, read your inbox, answer or complete a task. Only send and send_message skip preview and confirmation. "
"Send requires readable source data for every recipient, person and AI attribution, and an hourly connection limit. "
"Answer and complete require preview and confirmation. Access requests need human approval to grant access.",
"actions": {
"list_team": {"read": True, "destructive": False, "confirm": False, "handler": list_team, "schema": _schema({})},
"send_message": {"read": False, "destructive": False, "confirm": False, "handler": send_message,
"schema": _schema({
"to": {"type": "string", "minLength": 1},
"kind": {"type": "string", "enum": ["question", "change"]},
"text": {"type": "string", "minLength": 1, "maxLength": agent_inbox.TEXT_LIMIT,
"description": "Without a source, use only: " + " ".join(_SOCIAL_MESSAGES)},
"change": {"type": "string", "minLength": 1, "maxLength": agent_inbox.TEXT_LIMIT,
"description": "Required for kind change. Describe the proposal, never executable instructions."},
"source": _schema({"database": {"type": "string"}, "record": {"type": "string"}}, ("database",)),
}, ("to", "kind", "text"))},
"check_inbox": {"read": True, "destructive": False, "confirm": False, "handler": check_inbox, "schema": _schema({})},
"ask_user": {"read": False, "destructive": False, "confirm": True, "handler": ask_user,
"receipt_access": _approval_access,
"schema": _schema({"id": {"type": "string"},
"decision": {"type": "string", "enum": ["Approve", "Deny"]}}, ("id", "decision"))},
"send": {"read": False, "destructive": False, "confirm": False, "handler": send,
"schema": _schema({
"to": {"type": "array", "items": {"type": "string"}, "minItems": 1,
"maxItems": tickets.MAX_REQUEST_RECIPIENTS},
"kind": {"type": "string", "enum": list(tickets.REQUEST_KINDS)},
"title": {"type": "string", "minLength": 1}, "body": {"type": "string"},
"source": _schema({"database": {"type": "string"}, "record": {"type": "string"}}, ("database",)),
}, ("to", "kind", "title", "body"))},
"inbox": {"read": True, "destructive": False, "confirm": False, "handler": inbox, "schema": _schema({})},
"answer": {"read": False, "destructive": False, "confirm": True, "handler": answer,
"receipt_access": _receipt_access,
"schema": _schema({"id": {"type": "string"}, "body": {"type": "string", "minLength": 1},
"state": {"type": "string", "enum": ["working", "input-required", "rejected"]}},
("id", "body"))},
"complete": {"read": False, "destructive": False, "confirm": True, "handler": complete,
"receipt_access": _receipt_access,
"schema": _schema({"id": {"type": "string"}}, ("id",))},
},
}