Metadata-Version: 2.4
Name: project-agent-client
Version: 0.1.1
Summary: Remote Project Agent command-line client
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# Project Agent CLI

Install the client with `python -m pip install project-agent-client`, or install
from this repository with `python -m pip install ./apps/cli`. Build a wheel
with `python -m build apps/cli` for distribution. The installed
entry point is `project-agent`; do not install it into the same environment as
the legacy backend package, which exposes the same command name.

This separately packaged client forwards Task, Query, Sprint and Proposal scene
commands, Quest Task handoffs, and explicitly supported Context, Doc Hub,
Meeting, Bootstrap, Attribute, Report, Monitoring and Scheduled commands.
The service must implement and authorize each operation; this client cannot
override a service-side rejection. Scene receipts and the stdout, stderr and
exit code of bridged commands are preserved. Administrative database and
upgrade operations are not exposed through this client. The server's database
location is never selected by a client-supplied path.

Configure `PROJECT_SERVICE_URL` and set `MAGIC_CAMPUS_API_KEY` to your Magic
Campus API Key (access token). You can instead set `PROJECT_SERVICE_TOKEN` to
an API Key or existing service grant; a non-empty `PROJECT_SERVICE_TOKEN` takes
precedence when both are set. The client sends the selected credential as
`Authorization: Bearer <token>`; it does not need Magic Campus account
API settings or service database credentials. HTTPS is required
except for a local loopback service. The client does not automatically retry a
write because a network failure can leave its outcome unknown. Legacy Doc Hub
JSON-file arguments are read on the client and sent as inline JSON; paths are
never read on the server. A Magic Campus API Key acts only for its verified
user; it cannot delegate another actor. Commands that mutate data require an
active user and the applicable project membership. Existing trusted Agent
grants can still supply a verified per-request actor.

With a personal Magic Campus API Key, Task and Sprint scene writes continue to
enforce their actor and business rules, and Task Quest commands remain available
with their own authorization checks. Proposal `list` is readable, while
`approve` and `reject` require a trusted service grant because the existing
policy does not yet enforce approval eligibility. For Story/People Quest
sources, personal keys may use status, query and detail; private query scopes
must match the caller's active Magic Campus identity. The source operations
ingest, publish-source, reconcile and history require a trusted service grant
and an active actor: history also updates the shared review journal. The grant
must bind the actor or explicitly allow per-request delegation. The CLI bridge supports the
read-only context commands, Doc Hub reads (`get-root`, `index`, `access target`,
`access plan`), `meeting parse-time`, `meeting tasks pending`, `mind read`,
`loop list`, and `monitoring evaluate-followups`; it also supports
`attribute apply` and `meeting save`, which check project membership.

Other bridge commands require a configured trusted service grant: context
member/identity management, onboarding, all bootstrap commands (including
`checkpoint` and `loop-state`, which update state), Doc Hub writes, report,
monitoring writes, scheduled runs, meeting task plan/placement/run/resume, and
loop writes. These commands do not yet all enforce caller authorization. The
service grant must have a bound actor or explicitly trust per-request delegation
for writes. A personal API Key cannot be used to bypass this restriction.

With a trusted service grant, meeting `tasks run` and `tasks resume` execute on the service, using the bound
actor. Existing plans must resolve to that actor; a resume batch with a plan
for another actor is rejected. Task writes use the service-side Quest handoff.
Meeting notifications are sent by the service's `magic-campus` executable, so
that executable and its account configuration must be available in the service
runtime; an absent executable leaves the notification pending for retry.
The meeting-assistant skill uses the same `PROJECT_SERVICE_URL` and
`PROJECT_SERVICE_TOKEN` for meeting state when those are set, and does not
fall back to a local database if the remote service is unavailable.

When an explicitly trusted Agent credential uses `trustActorRefs: true`, the
runtime must set `PROJECT_SERVICE_ACTOR_REF` to the current verified actor JSON
(e.g. `{"userId":"..."}`) for CLI bridge operations which need a user. A bound
actor credential does not need this variable. The service validates that actor
is active and rejects a conflicting actor in the command input.
