Personal tools and trusted account management¶
Registry v20 retains 67 executable personal tools alongside 51 financial/discovery
entries. Existing financial names, input and result contracts remain supported.
The public argus:tools:public whitelist covers everyday financial research. Advanced
and diagnostic tools need explicit signed discovery grants plus data scopes. Explicit
signed personal domain scopes and current owner consent are required for private
reads/writes; they are never inherited from fact scopes. Search checks every
requested domain. Confirmation preparation checks its target operation.
Consumer OAuth connections on /mcp list only the 20
consumer tools, which return
consumer-result-v1. The tools on this page are neither
listed nor callable there; use their CLI and REST bindings.
The executable catalog is argus.contracts.personal_tools.PERSONAL_TOOLS and is
included in the authoritative registry, generated bindings, runtime OpenAPI,
MCP schemas and release schema catalog. personal_operations and
personal-contract-foundation.v1.json retain the earlier design/foundation and
do not independently activate operations. Inspect the current registry to learn
which operations are callable.
Requests and responses¶
REST and MCP use the same closed JSON request. Personal CLI commands use the
registry's hyphenated command and --request-file FILE; the file contains that
same request JSON. Authenticate using the existing OAuth login/secure credential
store. Credentials and ownership are never arguments in personal JSON.
personal-result-v1 carries result_kind, request_id, audit_id, and exactly
one of payload and problem. Payloads contain owner_id, lifecycle_id,
domain and the operation's typed data. Families distinguish private objects,
management, usage, tasks, confirmations and governed financial compositions.
Financial compositions preserve the original child packages, evidence, clocks,
source rights and audits. Saved queries execute through the canonical fact
service again. User notes remain labeled untrusted user content and are never
financial facts or platform recommendations.
A research note has an optional note_kind, note or question (a pinned
question). personal_notes_create_v1 and personal_notes_update_v1 accept it,
and an update that omits it keeps the stored kind. A note's record returns it,
and so does the note's hit in personal_search_read_v1. Tags are the owner's
own words and never decide the kind. A note stored before the field existed
has none: its record leaves the field out, and its search hit reads question
only when the note carries the question tag that marked it then.
The earlier six foundation result schemas remain available; clients use the
per-tool output schema for the new business DTOs. Existing financial invocation
responses retain CliToolEnvelope. HTTP authentication and schema failures may
precede core entry. Personal validation responses exclude input values. MCP
clients first check transport errors/isError and then decode the typed result.
The existing documentation site validates personal request schemas, saved-query definitions, confirmation target requests and filing selection completeness. Object, preview and confirmation identifiers refer to earlier steps under the user's authorization. Local demo credentials cannot execute private operations: the documentation harness checks refusal through REST, remote CLI and MCP. Authorized personal success is covered separately by the real PostgreSQL/Redis interface parity suite. Structural business-input validation does not establish owner access, source coverage or mutation success. The harness reuses its CLI command tree and MCP catalog while preserving each individual invocation and assertion.
Writes, retries and confirmation¶
Inspect the generated mutation_policy and MCP annotations. Ordinary CRUD keys
bind owner, lifecycle, operation and input; edits/deletes use the current object
version. A reused key with different input fails. Read acknowledgement sets read
once. Preview creation, expiring download-reference issuance, preference version
updates and confirmation preparation explicitly declare their distinct retry
behavior; they are not advertised as unconditional idempotent writes.
Import commits bind the preview, selected rows, replacements and owner-approved
confirmation. Deleting a list that affects subscriptions similarly binds all
affected versions. Removing watchlist members needs a confirmation only when
one call names more than 50 of them; up to 50 are removed directly. Preparing
confirmation is permitted to the originating Agent;
approval belongs to the trusted account session. An Agent-provided confirmed
flag, owner identity, arbitrary sensitive operation or hidden tool cannot approve
or perform account revocation, deletion or identity changes.
The owner may approve an ordinary bulk plan created for a configured API or MCP resource. Approval checks owner/lifecycle, active account, stored operation, versions and expiry under the account lock; it preserves the plan's original client, resource and digest. The consuming Agent must still match those bindings. Sensitive account confirmations remain bound to the trusted web management resource.
Downloads¶
personal_exports_download_v1 issues a private 300-second reference. POST it in
the JSON body to /v1/personal/export-content, with an optional byte offset,
using the same authenticated context. CLI also exposes personal-export-content
--request-file FILE --output FILE; it requires a new output path and writes a
bounded temporary file before atomic delivery. An offset produces the remaining
bytes for an explicitly managed resume. Every emitted chunk rechecks the existing
owner, grant, source, lifecycle and expiry rules. References are never URLs or
object-store signed links. A stopped stream is incomplete; downloaded bytes
cannot be recalled.
This byte-only endpoint verifies either the API or MCP resource's original credential. The download reference must still match that exact resource, client, session, owner and lifecycle; an API credential cannot consume an MCP-bound reference. Ordinary REST business endpoints continue to require the API resource. No audience exchange or broader business grant is implied.
Personal CLI discovery declares JSON-file arguments and credentials from the
secure store or environment. MCP and REST accept the same closed JSON object.
The existing binding maps reserve $request for the whole JSON file
(parameter_encodings: json_file, parameter_aliases: request_file), preserving
the v18 registry model's closed field set.
All three transports allow the frozen 5 MiB CSV input, including bounded JSON
escaping and protocol overhead; business file, row and storage limits are
unchanged.
Personal CLI requests refuse HTTP redirects so a bearer or private body cannot
be forwarded to a different endpoint. Authentication failures, capacity
refusals and business conflicts each produce one typed JSON result.
Trusted account API¶
The separate catalog release/personal-management.v1.json declares the
/account/api/* operations. These require the existing secure web cookie,
same-origin protection, cookie-bound CSRF and current terms. Sensitive operations
also require account:trusted_management, recent server-verified owner proof
and bound confirmation. Proofs are reused only within the same real session and
original five-minute deadline. Owner operations use the independent 60/minute
management window, not a financial-tool window. Request bodies and private
results are excluded from audits.
Prepare and confirm revocations or domain consent using the same effect and
confirmation identifier. consent-batch-prepare and consent-batch-confirm
change up to 16 distinct consent rows of one client under one confirmation;
the rows commit together, each with its own expected version. A changed effect/version is refused; a completed retry
returns only its original receipt. Bulk approval is limited to an existing
server-created import/list-deletion plan owned by the current account. Full
export and deletion remain owner-only. Identity changes link to the configured
identity provider, where verification occurs.
Deletion preparation returns the independent progress credential only in the
private body. Save and actually query it with POST
/account/api/deletion-progress before confirming. It continues after login is
disabled, and cannot access other data or cancel deletion. The server stores
only its irreversible verifier. Account APIs return no-store/no-referrer and do
not accept credentials in query parameters.
These adapters also back the personal pages and trusted account flows of the
Argus web app at /account/.
MCP HTTP calls use the authenticated identity attached to the current message, including nested financial calls. A long-lived protocol session cannot retain its opening scope or tool whitelist after the registered grant narrows.