tutti/packages/appcli/core

App CLI Core

packages/appcli/core owns the reusable Go implementation of the App CLI protocol contract used by workspace apps.

The package is intentionally limited to protocol-level behavior:

• tutti.app.cli.v1 manifest reading and validation
• command capability construction from a manifest and host-provided app metadata
• manifest input normalization
• tutti.app.cli.invoke.v1 HTTP invoke envelopes
• handler response decoding and output contract validation
• wait-command execution metadata and validated pending continuations
• scope conflict and reserved-scope state calculation

Host products keep their own workspace lookup, durable state, app package metadata, runtime startup, and user-facing status DTO adapters outside this module. Tutti daemon integration lives in services/tuttid/service/cli/appcli.

The protocol strings still use the frozen Tutti App CLI contract for backwards compatibility with existing app manifests and handlers. That does not make this module a Tutti daemon business layer; consumers such as TSH can reuse the protocol core while supplying their own host adapters.

Wait commands

An app command that semantically waits for a run, session, or other durable execution declares execution.mode as wait. Its handler returns an ordinary final output when the execution reaches a stop point. While the execution is still active, the handler returns a validated continuation with state pending and a bounded retryAfterMs delay.

The terminal CLI consumes continuations automatically. One visible command therefore remains active across multiple handler invocations; callers do not poll and do not pass a follow flag. The CLI-owned --timeout-ms option is an optional total wait deadline. When it expires, the command returns a successful JSON observation with reason: "wait_timeout", timedOut: true, and executionContinues: true; it never cancels the underlying execution.

Handler timeoutMs remains a per-invocation transport budget. It is not a workflow or total wait timeout.