mainsequence-metatable 0.1.23.dev36__tar.gz → 0.1.24__tar.gz

mainsequence_metatable-0.1.24/.agents/skills/analyze-with-sql/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: analyze-with-sql
+description: Answer a data question by running read-only SQL on MetaTables and reporting the result with the SQL that produced it. Use when someone asks for numbers, trends, comparisons or rows from MetaTables data.
+---
+
+# Analyze with SQL
+
+Input: a data question. Output: the answer, the SQL that ran and the tables it read.
+
+1. Find the tables with the `discover-tables` workflow first; never guess names.
+2. Write one query in the dialect of the table's `engine`, using its physical name.
+   Establish the grain and join keys, filter time-index tables on their time index
+   within the covered range, and aggregate or `LIMIT` the query.
+3. Run it with `run_sql`, passing the uid of a table it reads. All tables in a query
+   must share that table's DataSource. If the DataSource does not accept SQL, use
+   `preview_rows`.
+4. Fix failing SQL from the error message; never invent numbers.
+
+Report what the data shows, what you infer and what remains unresolved, and say when
+results were truncated. End with the SQL and the tables it read.
+
+Side effects: none. The database enforces the grants of the person you are answering and
+refuses writes.

mainsequence_metatable-0.1.24/.agents/skills/discover-tables/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: discover-tables
+description: Find, list and explain the MetaTables that hold some data, with their columns, time coverage and join keys. Use when someone asks where data lives or what a table or column means.
+---
+
+# Discover tables
+
+Input: a question or topic, optionally a namespace. Output: the tables that fit, why
+they fit, and how they join.
+
+1. Call `deep_search` with 3-6 short noun phrases that describe the data in different
+   words: the business concept, synonyms and likely column names. Search again with
+   more synonyms when phrases come back keyword-only.
+2. Read the described candidates: description, matched columns, time index and covered
+   range, and foreign keys. Use `describe_table` for any table you name that was not
+   described, including `related` tables that supply join keys.
+3. To show what data exists, use `list_namespaces` for the data areas and their table
+   counts, then `list_tables` for one namespace.
+
+Answer with each table's identifier, namespace, uid and physical name, the columns that
+matter, and the join keys between them. When candidates compete, say which you would use
+and why. When nothing fits, say so.
+
+Side effects: none; every tool reads with the access of the person you are answering.

mainsequence_metatable-0.1.24/.agents/skills/ms_tau_sdk/PINNED_FROM.txt

@@ -0,0 +1,7 @@
+schema=1
+library_name=ms-tau-sdk
+namespace=ms_tau_sdk
+pinned_version=2.0.7
+skills_path=src/ms_tau_sdk/agent_skills
+skills=tau_a2a_runtime_adapter,tau_local_development,tau_project_customization,tau_repository_integration,tau_security_and_access
+command=ms-tau skills sync --path .

mainsequence_metatable-0.1.24/.agents/skills/ms_tau_sdk/tau_a2a_runtime_adapter/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: tau-a2a-runtime-adapter
+description: Implement and diagnose the TAU host side of Main Sequence A2A without duplicating the platform-owned protocol, authorization, discovery, and task-lifecycle contract.
+---
+
+# TAU A2A Runtime Adapter
+
+Use this skill only for `ms-tau-sdk` host behavior. Read the platform-owned `a2a_communication`
+skill first for canonical tool inputs, discovery, authorization, wire envelopes, task lifecycle,
+idempotency, and retry semantics.
+
+## Ownership boundary
+
+The platform owns:
+
+- canonical `a2a.*` MCP schemas and platform discovery;
+- AgentSession and AgentTask lifecycle;
+- exact runtime-access authorization;
+- caller-session proof validation; and
+- direct-runtime protocol and response-kind semantics.
+
+The SDK owns:
+
+- projecting the authenticated Main Sequence MCP catalog into a TAU session;
+- preserving each tool's canonical name and metadata through host normalization;
+- privately attaching, to every hosted Main Sequence MCP call, the turn's caller-session proof under
+  `mainsequence.ai/caller-session-proof/v1`, and, while the turn serves a person, the same proof as
+  that person's delegation under `mainsequence.ai/delegation/v1`. No tool metadata decides it;
+- verifying the platform's signed caller or platform assertion on every inbound request of a
+  hosted runtime, and admitting a request to a session or its Tasks only for the session's owner,
+  an Organization admin, or the workload User of the Agent that delegated to that child session,
+  which the platform's own records establish, never the `X-Caller-*` headers;
+- presenting the verified caller assertion of the request that starts a chat or A2A Message turn
+  only when it marks that turn active, so that the platform can record the turn's requester;
+  taking the person the turn serves only from the platform's answer to the turn start; and giving
+  extension tools that person and calls for the work through `current_requester()` and
+  `platform_client()` without exposing the assertion, the lease proof, or any token;
+- translating inbound A2A requests into the shared TAU runtime; and
+- translating runtime events and results into validated A2A responses.
+
+Do not hard-code behavior from a rendered host-tool name. Inspect the canonical tool record and its
+`_meta` marker. The proof belongs under request `_meta` key
+`mainsequence.ai/caller-session-proof/v1`; it is never a model-visible argument.
+
+## Managed runtime behavior
+
+For a protected call, the active session must provide its exact UID, lease holder, and lease token.
+The SDK attaches that proof only to the individual MCP call that requested it. It must not expose,
+log, persist, or reuse the proof as general authorization.
+
+## Send Work To Another Agent
+
+For a deployed Agent, use the projected `a2a.send_message` MCP operation. The platform creates or
+resolves the target `AgentSession`, waits for its runtime to become ready, and dispatches the
+message. For asynchronous work, use the returned Task handle with `a2a.wait_task`.
+
+For local Tau development, start `ms-tau` and wait for its local `/ready` result. The public A2A
+REST and JSON-RPC surfaces support Message and Task execution against the workspace-local SQLite
+store, including streaming, list/get/cancel/subscribe, and continuation. An A2A protocol Task does
+not require a platform AgentSession.
+
+Outbound work to a deployed Agent still uses `a2a.send_message` through Main Sequence MCP. Message
+and Task-with-polling flows use the authenticated user. `resume_caller` requires a registered
+platform callback target and is therefore unavailable to an unregistered local process.
+
+If proof is unavailable or stale, surface the platform error. Never fabricate an AgentSession,
+lease, target identity, or Environment selection. The SDK does not reinterpret requester/responder
+wire direction as caller identity.
+
+## Local-mode behavior
+
+Local mode has no registered Agent or AgentSession and therefore cannot supply deployed caller
+proof or appear in platform discovery. Public local Message and Task coordination is nevertheless
+supported through local context identities and SQLite persistence. Only internal backend dispatch,
+caller delivery, push notifications, platform discovery, and `resume_caller` retain the documented
+capability boundary. Main Sequence MCP remains available for authenticated-user A2A semantics.
+
+## Diagnostics
+
+When an A2A operation fails, identify the boundary before changing code:
+
+1. Catalog projection: canonical tool or `_meta` marker missing.
+2. Host adaptation: private proof not attached to the marked call.
+3. Platform authorization: proof rejected, target disallowed, or Environment mismatch.
+4. Runtime access: endpoint, token, or release bundle stale.
+5. Wire validation: request/response role, context, extension, or payload invalid.
+6. Task lifecycle: fence, lease, cancellation, event order, or retry semantics violated.
+
+For Task lifecycle diagnosis, derive terminality from the Task state; never introduce a second
+terminal flag. Normal execution errors must settle `failed` and streaming must emit that
+authoritative terminal status update. `task_terminalization_unknown` means settlement durability
+is unknown and belongs to the recovery owner. Local SQLite recovery is SDK-owned; managed dispatch
+recovery is backend-owned. Do not retry a stale working attempt when project or MCP side effects may
+have occurred unless a checkpoint or idempotency contract proves replay safe.
+
+Treat Task Messages, Artifacts, Tau entries, Task events, and logs as separate ontologies. Use
+`historyLength` only for the bounded durable Message tail. Omission means the SDK default of 100,
+zero omits history without a tail read, and positive values return the latest bounded tail in
+oldest-to-newest order. Public A2A v1 roles are `ROLE_USER` and `ROLE_AGENT`; persistence uses the
+Main Sequence requester/responder direction values. Never expose internal Tau entries, reasoning,
+tool traffic, prompts, or logs as public Task history.
+
+Allocate the Tau turn UID before attempt start and pass that exact UID to the runtime prompt. A
+Task attempt owns one turn and one half-open entry interval with a `committed` or `abandoned`
+resolution. Do not correlate by timestamps. A status settlement is absent or one complete durable
+responder Message; never send the removed ad hoc status-detail shape. Status events reference that
+Message and consumers reload the Task snapshot.
+
+Change this SDK only for catalog projection, proof attachment, runtime execution, or transport
+translation defects. Platform contract changes are made in the platform, not in this SDK.

mainsequence_metatable-0.1.24/.agents/skills/ms_tau_sdk/tau_local_development/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: tau-local-development
+description: Run and diagnose Main Sequence TAU SDK local mode, including live provider and MCP access, workspace SQLite persistence, and public local A2A Message and Task workflows.
+---
+
+# TAU Local Development
+
+Use this skill when developing a repository that embeds `ms-tau-sdk` without creating platform
+Agent or AgentSession runtime records. Local mode changes where runtime state is stored. It is not
+an offline, mock-provider, or mock-MCP mode.
+
+## Start the process
+
+The user logs in once with a Main Sequence CLI that provides `mainsequence auth token`. Local mode
+then asks that CLI for a short-lived access token, at startup and again when the token is about to
+expire. No token is exported and none is written to the project `.env`. The SDK does not install or
+import the `mainsequence` Python package and does not read the CLI's private credential store.
+
+```bash
+mainsequence login   # once; the session is kept by the CLI, not in .env
+
+export MAINSEQUENCE_AUTH_MODE=jwt
+export TAU_LOCAL_MODE=true
+export TAU_LOCAL_PROVIDER="<provider>"
+export TAU_LOCAL_MODEL="<model>"
+# Optional:
+export TAU_LOCAL_THINKING="<thinking-level>"
+
+uv run ms-tau
+```
+
+The SDK looks for the CLI in `MAINSEQUENCE_CLI`, then beside the Python interpreter that runs
+`ms-tau`, then on `PATH`. Launchers and CI can export `MAINSEQUENCE_ACCESS_TOKEN` and
+`MAINSEQUENCE_REFRESH_TOKEN` instead. With both set, the SDK uses that pair and never runs the
+CLI. Do not add token lines to `.env`. A pair found there still works, but it is deprecated and
+startup logs a warning. `mainsequence refresh-token` run in that directory removes the lines.
+
+Do not set `APP_NAME`, `FASTAPI_PUBLIC_BASE_URL`, `MAINSEQUENCE_CALLER_AUTH_MODE=assertion`, or the
+`MAINSEQUENCE_CALLER_ASSERTION_*` variables. The platform sets them when it hosts a runtime, and
+local mode refuses to start with them.
+
+Set `MAINSEQUENCE_ENDPOINT` only for a non-default platform endpoint. The CLI session must be for
+the same endpoint. Local mode binds to `127.0.0.1:8787` by default. Treat an explicit public bind
+as privileged exposure: each accepted request can use the authenticated user's live Main Sequence
+permissions.
+
+Never place JWTs or provider credentials in source control, `.tau`, copied skills, command output,
+or debugging artifacts. Do not run `mainsequence auth token` to read its output: it prints the
+access token. The user JWT is sent only to Main Sequence. Main Sequence validates the
+explicit `TAU_LOCAL_PROVIDER` and `TAU_LOCAL_MODEL`, returns provider-control evidence, and hydrates
+the provider credential used for inference. Provider secrets are neither environment settings nor
+local state.
+
+## Exact local/remote boundary
+
+| Concern | Local-mode behavior |
+| --- | --- |
+| Agent or AgentSession registration | Never created or updated |
+| Chat history, snapshots, leases, activity, and cancellation | Workspace SQLite |
+| Public A2A Message and Task state | Workspace SQLite |
+| Main Sequence authentication and token refresh | Remote. The token comes from the Main Sequence CLI session, or from an exported JWT pair |
+| Provider authorization, hydration, and inference | Remote and real |
+| Main Sequence MCP catalog and tool calls | Remote and real; platform mutations remain possible |
+| Project instructions, skills, hooks, and extensions | Normal repository `.tau` composition |
+
+The database defaults to `~/.tau/mainsequence/<workspace-hash>/runtime.sqlite3`; override its
+parent only with `TAU_LOCAL_STATE_ROOT`. Local state is never uploaded or attached to a platform
+AgentSession when local mode is disabled. Stop all processes for the workspace before moving or
+deleting its workspace-hash directory.
+
+Local operational events are also written as structured JSON Lines to
+`~/.tau/mainsequence/<workspace-hash>/logs/tau.jsonl` (or beneath `TAU_LOCAL_STATE_ROOT`). The
+file sink is mandatory in local mode even when console logging is enabled. Read the current file
+and its five rotated backups when diagnosing startup, provider, MCP, A2A, or project-extension
+failures. The SDK log does not capture arbitrary extension `print()` output; project-owned code
+must use propagating Python logging and must not log secrets or prompt/tool payloads. A failure to
+open the file stops startup; the logs are never uploaded to an AgentSession.
+
+## Public local A2A contract
+
+An A2A protocol Task is local coordination state, not a platform `AgentTask`, and does not require
+a platform AgentSession. Local mode supports:
+
+- REST `POST /api/a2a/v1/message:send` and JSON-RPC `message/send` for Message or Task execution;
+- REST `POST /api/a2a/v1/message:stream` and JSON-RPC `message/stream` for SSE Task execution;
+- REST `GET /api/a2a/v1/tasks`, `GET /api/a2a/v1/tasks/{task_id}`,
+  `POST /api/a2a/v1/tasks/{task_id}:cancel`, and
+  `GET /api/a2a/v1/tasks/{task_id}:subscribe`;
+- JSON-RPC `tasks/list`, `tasks/get`, `tasks/cancel`, and `tasks/subscribe`;
+- subscription resumption with `afterSequence`;
+- continuation of a Task in `input_required` or `auth_required` by sending a new Message carrying
+  that `taskId`; and
+- Task status, messages, artifacts, attempts, and events surviving process restart, with the SDK
+  rescheduling safe unclaimed work and terminalizing stale uncertain work rather than replaying
+  possible side effects.
+
+For a chat UI over `POST /api/chat`, do not read `runtime.sqlite3` or keep a browser-only
+transcript either. List sessions with `GET /api/local/v1/chat-sessions?limit=<n>&cursor=<opaque>`
+and hydrate one with `GET /api/local/v1/chat-sessions/{sessionUid}/history`. The history has the
+platform's `GET /api/v1/agent-sessions/{uid}/history/` shape, including reasoning, tool calls with
+results, and a running turn in `inProgressMessage`, so one reader serves local and deployed
+Agents. Reuse the listed `sessionUid` in `POST /api/chat`. A local chat turn keeps running when
+the client disconnects or reloads; stop it only with `POST /api/chat/session/cancel`, and queue a
+new message while a session is `working` (`POST /api/chat` returns 409 `session_busy`). Title the
+UI from `GET /api/local/v1/agent`, which reads the workspace's `.agents/agent_card.json`.
+
+For the default direct Message flow, do not read `runtime.sqlite3` or keep a browser-only source of
+truth. Discover conversations with `GET /api/local/v1/conversations?limit=<n>&cursor=<opaque>` and
+hydrate the latest bounded Message tail with
+`GET /api/local/v1/conversations/{contextId}/messages?limit=<n>&beforeSequence=<n>`. Reuse the
+listed canonical `contextId` in `message:send`. These are Main Sequence local SDK extensions, not
+A2A v1 methods. They contain only persisted public `ROLE_USER`/`ROLE_AGENT` Messages and are
+separate from `Task.history`, Tau entries, tools, reasoning, events, and logs.
+
+To request a Task from `message:send`, send the response-kind extension header
+`A2A-Extensions: https://mainsequence.ai/a2a/extensions/response-kind/v1` together with
+`configuration.responseKind: "task"`. Omit that selection for the default completed Message
+response. `message:stream` is always Task-oriented and does not accept `responseKind` or
+`returnImmediately`.
+
+Task terminality is derived only from its A2A state. `completed`, `failed`, `canceled`, and
+`rejected` are terminal; `input_required` and `auth_required` are resumable. A normal execution
+failure produces a durable failed Task and a standard responder `status.message`. A
+`task_terminalization_unknown` stream error means the terminal write itself could not be proven;
+retrieve or subscribe to the Task while recovery resolves it. Never treat an HTTP disconnect or
+bounded wait expiry as Task cancellation.
+
+Task responses include a bounded Message tail by default. Set `configuration.historyLength` on
+Message send/stream or `historyLength` on Task get/list: zero omits history and performs no tail
+read, while a positive value returns the latest Messages oldest-to-newest, capped at 100. History
+contains requester and deliberately durable responder/status Messages only. Final output remains
+under `artifacts`; Tau entries, tool activity, events, and logs never become public history. Public
+roles are `ROLE_USER`/`ROLE_AGENT`; the local SQLite binding stores requester/responder directions.
+
+Each local Task attempt reserves one immutable Tau turn. Its entries share that turn UID and remain
+inside the recorded half-open sequence interval. Completed and interrupted settlement requires a
+committed turn; failed, rejected, or canceled settlement can abandon a pending turn, after which
+late append or commit is rejected. An unresolved Task-owned turn prevents lease replacement until
+the local Task reconciler records its recovery outcome. Ordinary chat/direct-Message turns have no
+Task owner and retain normal lease cleanup.
+
+After restart, the local reconciler schedules an unclaimed `submitted` Task from its persisted
+request. It does not blindly rerun a stale `working` Task: once the old lease and stale interval
+expire, an attempt without replay-safe checkpoint evidence becomes failed with
+`ambiguous_execution_outcome`. Inspect the failure code, attempt, recovery owner, and correlation ID
+in Tau Board and the structured log.
+
+Incoming local A2A requests do not need managed-gateway `X-Caller-*` headers. TAU assigns
+workspace-local provenance and maps each supplied `contextId` into the same workspace-scoped local
+session namespace used by chat. A supplied `taskId` remains the public Task identifier. The local
+`GET /api/a2a/v1/extendedAgentCard` response advertises Message, Task, and streaming support while
+disabling push notifications.
+
+The following remain unavailable because they require registered platform routing or callback
+identity:
+
+- platform discovery of the unregistered local process;
+- `/internal/a2a` backend dispatch and caller-delivery hooks;
+- A2A push-notification configuration; and
+- `resume_caller` Task completion.
+
+These are the only A2A-adjacent capability boundaries; public local Message and Task requests must not return
+`local_mode_capability_unsupported`.
+
+Each standard A2A Task carries the time its current state was recorded in
+`task.status.timestamp`. For `TASK_STATE_COMPLETED`, that is the completion time. The A2A Task
+object has no standard top-level creation timestamp; Tau persists `created_at` in local SQLite,
+and Tau Board joins that local row when it displays the A2A Task list. Do not invent extra A2A
+wire fields for Board presentation.
+
+## Inspect and test with Tau Board
+
+Install `ms-tau-sdk[tau-board]`, run `tau-board` as a separate process, and connect it to the
+loopback local-mode Tau endpoint. The Agent tab requires an already loaded session: first send a
+Chat or A2A request, then select that session. It shows the effective Agent Card, loaded tools by
+source, project extension diagnostics, and registered project extension entry source.
+
+Only project-extension tools with an object JSON Schema are runnable in the workbench. Select the
+tool, fill its generated form or raw JSON, validate the exact canonical arguments, acknowledge
+the side-effect warning, then run it. Validation never calls the tool. Run invokes the exact
+loaded tool without a model call and without adding chat entries, A2A Tasks, or artifacts. The
+tool still has the Tau process's real filesystem, network, environment, and credential access;
+there is no automatic rollback. A busy session, stale catalog, expired confirmation, non-project
+tool, oversized output, timeout, or cancellation must fail explicitly.
+
+The Tasks tab is the primary inspection surface: Overview states the lifecycle, Conversation shows
+durable Messages, Result shows complete Artifacts, Execution uses exact attempt/turn correlation,
+and Technical retains mutation events and logs. **Open in A2A Console** is an action shortcut, not
+the Task explanation. Many `output_updated` records represent revisions of one Artifact and must
+not be interpreted as many agent responses.
+
+## Outbound A2A through Main Sequence MCP
+
+Keep the projected `a2a.send_message` tool available. A local agent may send a Message or create a
+Task for a deployed Agent using authenticated-user semantics. For a Task, use
+`completion_policy: "poll"` and use the returned Task handle with `a2a.wait_task`. Local mode rejects
+`completion_policy: "resume_caller"` because it has no registered callback target and never
+fabricates caller-session proof. Other live MCP tools remain available and can read or mutate real
+platform resources under the authenticated user's permissions.
+
+## Verify the runtime
+
+Check the process in this order:
+
+1. `GET /health` reports `mode: local`, safe composition diagnostics, and
+   `mainsequence_auth_source`: `cli`, `environment`, or `env_file`.
+2. `GET /ready` confirms user authentication, provider control, local storage, and MCP readiness.
+3. `GET /version` reports the expected installed SDK release.
+4. A chat request without `sessionUid` returns an effective identifier in
+   `X-Agent-Session-Uid`; reuse it to resume the conversation.
+5. A REST `POST /api/a2a/v1/message:send` without gateway caller headers returns a Message.
+6. Repeat it with the response-kind extension and `configuration.responseKind: "task"`; verify
+   the Task through `GET /api/a2a/v1/tasks/{task_id}` and after a process restart.
+7. Verify `POST /api/a2a/v1/message:stream`, cancellation, subscription, and continuation for the
+   project workflow being developed.
+
+## Classify failures
+
+- Startup setting failure: inspect the exact missing or conflicting environment variable.
+- Authentication failure: read the error, which names its remedy. The user runs
+  `mainsequence login`, upgrades a Main Sequence CLI that is too old for `auth token`, sets
+  `MAINSEQUENCE_CLI`, or provides the JWT pair. With an exported pair, export a fresh one. Do not
+  substitute a runtime credential in local mode.
+- Provider/model rejection: verify the exact configured names against the authenticated live
+  catalog; do not silently select a different model.
+- OpenAI-compatible transport failure: open the Task's failure incident in Tau Board. Use its
+  concrete HTTPX type, transport phase, attempt count, provider duration, failure UID, and bounded
+  traceback frames; expand raw JSON only for additional correlation fields. Do not infer a timeout
+  when the dependency explicitly reports that its cause was unavailable.
+- MCP failure: distinguish catalog/connectivity failure from server-side authorization. A tool
+  genuinely requiring caller AgentSession proof must fail explicitly without causing registration.
+- Session conflict: keep one provider/model/thinking selection for an existing local session or
+  intentionally use a new local state namespace.
+- Public local A2A capability error: treat it as a stale or defective SDK. Capability errors are
+  valid only at the unsupported routing/callback boundaries listed above.
+- Project behavior failure: inspect `.tau` resources and extension diagnostics using
+  `tau-project-customization`.

mainsequence_metatable-0.1.24/.agents/skills/ms_tau_sdk/tau_project_customization/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: tau-project-customization
+description: Customize project-owned TAU instructions, skills, prompts, hooks, and extension tools while preserving SDK-owned transport and protocol invariants.
+---
+
+# TAU Project Customization
+
+Use this skill when changing the effective agent behavior of a repository that runs
+`ms-tau-sdk`. The project already executes arbitrary code in the runtime process, so the project
+owns and is responsible for its TAU resources and extensions.
+
+## One configuration boundary
+
+The workspace `.tau/` directory is the project behavior boundary:
+
+```text
+.tau/
+├── SYSTEM.md
+├── prompts/
+├── skills/
+└── extensions/
+```
+
+Creating `.tau/SYSTEM.md` replaces the packaged default general system instructions. There is no
+second SDK-specific prompt override or companion append file. Other resources follow the TAU
+version pinned by the installed SDK.
+
+`.agents/skills/ms_tau_sdk/` is different: it contains managed development instructions for coding
+agents working on the repository. It is not loaded as the runtime's `.tau` behavior and must not be
+used as application configuration.
+
+## Extension ownership
+
+Project extensions belong under `.tau/extensions/` and may add tools, hooks, and lifecycle
+behavior. Keep reusable business logic in the normal application package and make extension
+adapters thin and structured.
+
+The project author owns:
+
+- extension source, behavior, and tests;
+- Python and operating-system dependencies;
+- outbound network access and third-party credentials;
+- compatibility with the pinned SDK and TAU versions; and
+- reload, cancellation, and shutdown behavior.
+
+The SDK does not sandbox these extensions. Web, fetch, search, browser, video, and other optional
+tools are project choices and are not part of the base SDK.
+
+## Runtime tool composition
+
+Two independent process settings select the host-provided tools. Both default to `false`:
+
+| Setting | Effect when `true` |
+| --- | --- |
+| `TAU_EXCLUDE_BASE_TOOLS` | Replace Tau's `read`, `write`, `edit`, and `bash` with a skill-scoped `read`. |
+| `TAU_EXCLUDE_MAINSEQUENCE_MCP` | Skip Main Sequence MCP connection, tools, resources, and resource prompt. |
+
+Set them in `harness_agent.spec.env_vars` in a managed repository workflow, in the process
+environment for local `ms-tau`, or through explicit `TauSDKSettings` fields in a Python host. They
+apply to all sessions in that process; neither Agent Card skills nor prompt text removes tools.
+
+The accepted, pending job-hosted batch entry point uses these same two settings. It must not
+start Main Sequence MCP or add coding tools when the corresponding source is excluded. The table
+below describes the currently implemented service and local modes; batch behavior for A2A-only
+Task controls requires an actual Task context and is specified by ADR 0015.
+
+| Exclude base tools | Exclude Main Sequence MCP | Model-facing sources |
+| --- | --- | --- |
+| `false` | `false` | Coding tools, Main Sequence MCP, project extension tools, A2A Task controls. |
+| `true` | `false` | Skill-scoped `read`, Main Sequence MCP, project extension tools, A2A Task controls. |
+| `false` | `true` | Coding tools, project extension tools, A2A Task controls. |
+| `true` | `true` | Skill-scoped `read`, project extension tools, and A2A Task controls. |
+
+The A2A Task controls are `task_request_input` and `task_request_authorization`. They remain
+available in every mode for the agent's own Task; extensions must not register those names.
+Register project tools under `.tau/extensions/` and verify the effective catalog after loading.
+With base tools excluded, the skill-scoped `read` keeps `.tau/skills/` available: it opens a
+discovered skill's `SKILL.md` and the files in its directory, such as `references/*.md`, and
+rejects every other path, including symlinks that resolve outside the skill. Tau lists the skills
+in the system prompt because a tool named `read` exists. Extensions must not register `read` in
+this mode.
+Excluding coding tools does not sandbox extension Python code.
+
+## Invariants extensions must not replace
+
+Extensions may change effective agent capabilities, but they must not replace or bypass:
+
+- Main Sequence runtime or user authentication;
+- provider-control evidence and credential hydration;
+- caller identity, the turn's requester, and active-session proof;
+- persistence ordering, leases, cancellation, or task settlement;
+- secret redaction and payload limits; or
+- HTTP, SSE, Responses, and A2A wire validation.
+
+When Main Sequence MCP is enabled, use its canonical operations for live platform state. Project
+tools do not grant new platform permissions merely because they run inside TAU.
+
+## Acting for the person a turn serves
+
+An Agent that an Organization admin enabled for it can call the platform and other platform
+applications with the ordinary permissions of the person whose request a turn is serving: the
+requester. The platform keeps that authority and finds the person in its own records; the runtime
+only proves which of its sessions it is working on. Extension tools use two SDK functions and
+nothing else:
+
+```python
+import json
+
+from tau_agent.messages import TextContent
+from tau_agent.tools import AgentToolResult
+
+from ms_tau_sdk import platform_client
+
+ANALYST_DATA_RELEASE_UID = "..."  # the release of the application to ask
+
+
+async def revenue_by_region(tool_call_id, arguments, signal=None, on_update=None):
+    # This tool answers each person with their own data, so it needs a person.
+    try:
+        answer = await platform_client(delegation="required").call_release(
+            ANALYST_DATA_RELEASE_UID,
+            "POST",
+            "/query",
+            json={"question": "revenue by region"},
+        )
+    except PermissionError:
+        return AgentToolResult(content=[TextContent(text="Ask me from your own conversation.")])
+    return AgentToolResult(content=[TextContent(text=json.dumps(answer.json()["rows"]))])
+```
+
+- `current_requester()` returns the person the turn serves, with `uid` and `team_uids`, or
+  `None`. The platform names that person when the turn starts, whoever called; it is `None` when
+  the platform names nobody, in local mode, and in code outside a turn. Only it names the
+  requester: never take a person's UID from tool arguments, the prompt, history, or a header.
+- `platform_client()` returns a client. `await client.request("GET", "/api/v1/...")` calls a
+  platform API path, and `await client.call_release(release_uid, method, path, ...)` calls another
+  platform application. Both return an `httpx.Response`.
+- By default (`delegation="auto"`) a call carries the person's delegation while the turn serves a
+  person, and is the Agent's own otherwise; the operation or application decides what it may do.
+  `delegation="none"` never carries it. `delegation="required"` raises a `PermissionError` before
+  sending when the turn serves nobody; use it in a tool that only makes sense for a person.
+- A call the platform refuses because the person's access ended (`code`
+  `requester_binding_invalid` or `runtime_lease_*`) raises a `PermissionError`: the turn is over,
+  the access was removed, more than 24 hours passed, or the Agent is not enabled. Catch it, say in
+  plain words that the request cannot be served, and never retry it as the Agent.
+
+Rules for tools that act for the requester:
+
+- Never handle proofs or tokens. The SDK attaches the session, the lease proof, and the
+  credentials itself. A tool never reads, logs, stores, or forwards them, passes a path rather than
+  a URL, and never sets `Authorization` or an `X-MainSequence-*` header.
+- A delegated call uses the person's ordinary permissions, including administrative ones; any other
+  call uses the Agent's own. Each operation decides what it needs. Never infer write permission
+  from view access.
+- This needs the platform's matching change, deployed in the same cutover; check the deployed
+  platform and the installed SDK before depending on it.
+- Return to the model only business results, such as rows, numbers, and names. Never return the
+  response object, its headers, a token, a proof, or a raw error body.
+- Keep nothing for another turn or another person. The delegation ends with the turn, and a task
+  the tool leaves running acts only as the Agent afterwards.
+- What a tool reads for a person belongs to that person's conversation. Do not write it to shared
+  stores, other Agents, or external systems.
+
+People who use such an Agent are told:
+
+> **This Agent works with your identity.** It can read, create, change, run,
+> share or delete only what your permissions allow through supported operations,
+> only while serving your request, and for at most 24 hours after you ask. It
+> uses your ordinary permissions, including administrative permissions, and
+> access is checked on every call. Your Organization's administrator approved it
+> to work this way.
+
+The statement describes delegated calls. The Agent's own grants and trusted extension code remain
+separate authority. Prompt injection can cause unintended changes, sharing, or deletion within the
+person's permissions, and completed writes can outlast the delegation. Only Organization admins
+enable this authority.
+
+For a complete example, a tool that uses a person's Secret without exposing it, and how sharing
+decides what a delegated call can reach, use `tau_security_and_access`.
+
+## Validation
+
+Verify each project-owned capability through its observable interface and focused tests. Check
+that documented tool names and schemas match the loaded catalog, lifecycle hooks clean up their
+resources, and health diagnostics report extension load errors without exposing prompt content or
+secrets.
+
+For interactive local verification, start Tau in local mode, load a session through Chat or A2A,
+then open Tau Board's Agent tab. Inspect the effective tool category, JSON Schema, extension entry
+source, and diagnostics. For a project-owned tool, fill the generated form or raw JSON, validate
+the canonical arguments, explicitly acknowledge the side-effect warning, and run it. This invokes
+the exact loaded tool without a model turn or conversation/Task-history entry. It is not a sandbox:
+filesystem, network, credential, and external-system side effects are the project's responsibility.