tRPC Procedures

projects

• projects.workflowSnapshot — Baseline workflow authoring and monitoring projection for the Projects surface.
  • Response includes canonical workflow definition, derived graph, recent runs, node projections, recent artifacts, recent traces, surface diagnostics, and workflowDefinitionSource — the resolved origin of the active workflow definition (inline for project-authored definitions, or an installed-package reference when the project uses a packageBindings entry).
• projects.workflowVisualDebugSnapshot — Advanced staged visual-debug projection for the Projects surface.
  • Response adds deterministic stage grouping, canvas node and edge overlays, MAO graph parity, checkpoint summary, and scheduler summary over canonical truth.
• projects.workflowNodeInspect — Returns rich node inspection for one project/run/node selection.
  • Response embeds the shared monitor projection plus reused MAO inspect truth, checkpoint posture, artifact lineage references, trace IDs, and policy-reason context.
• projects.dashboardSnapshot — Returns project health, blocked actions, schedules, escalation queue posture, package-default intake visibility, and linked workflow snapshot data.
• projects.configurationSnapshot — Returns the current project configuration, schedule records, blocked actions, and field provenance.
• projects.updateConfiguration — Applies governed project-configuration changes.
  • Rejects stale writes with CONFLICT when expectedUpdatedAt no longer matches the stored project.
• projects.upsertSchedule — Creates or updates a schedule bound to canonical workflow and workmode truth.
  • Returns BAD_REQUEST when the project has no canonical workflow definition and the caller does not supply workflowDefinitionId.
• projects.validateWorkflowDefinition — Validates a workflow draft on the server without persisting it.
• projects.saveWorkflowDefinition — Persists a validated canonical workflow definition and optionally sets it as the default.
  • Projection-only visual-debug fields are never accepted as canonical workflow-definition truth.

chat

• chat.sendMessage — Finalizes STM turn history in the core runtime before returning. Follow-up history reads reflect any pressure-triggered compaction for that project.
• chat.getHistory — Returns the current STM context: retained recent entries, optional summary, token count, and optional compaction state.

traces

memory

• memory.list — Returns the active durable entries for a project. Superseded or deleted records stay visible through memory.export, memory.audit, and memory.tombstones.
• memory.inspect — Inspect-first durable-memory query for the /memory UI.
  • scope accepts project, global, or all.
  • Filters accept free-text query, canonical types, lifecycleStatus, placementState, comma-ready tags, plus includeSuperseded and includeDeleted.
  • Sorting accepts updatedAt, createdAt, confidence, type, or sentiment with asc / desc.
  • Response shape: { entries, diagnostics }, where diagnostics includes requestedScope, projectInheritsGlobal, and optional globalScopeDecision when global inspection is requested.
• memory.learningOverview — Returns project-scoped distilled-pattern summaries for the Learning mode on /memory.
  • Filters accept free-text query, tier, decayState, and includeRetired.
  • Sorting accepts updatedAt, confidence, supportingSignals, or sourceCount with asc / desc.
  • Response shape: { items }, where each item includes the canonical pattern export, confidence signal, contradiction/staleness posture, source counts, and lineage-integrity diagnostics.
• memory.learningDetail — Returns learning detail for one distilled pattern or null when the pattern is unavailable in the requested project.
  • Input shape: { projectId, patternId }.
  • Response includes canonical pattern data, source timeline, derived lifecycle events, representative governance projections, lineage and rollback diagnostics, optional current control-state context, and explicit historicalDecisionLogAvailable: false.
• memory.denials — Returns denied memory-write candidates with operator-visible diagnostics.
  • decisionRecord preserves the canonical policy/governance decision when present.
  • traceId and timestamp let the UI link the denial back to the originating trace/turn.
• id with hard unset or false — Soft-delete a single entry (default delete mode)
• id with hard: true and rationale — Hard-delete path (requires principal override rationale and emits tombstone)
• projectId only — Soft-delete all active entries for the project
• memory.audit/memory.tombstones — Operator observability for mutation decisions, policy-governed denial outcomes, hard-delete proofs, and STM compaction audit records
• memory.export — Full project memory export including STM context (entries, summary, tokenCount, compactionState?), durable entries, audit history, and tombstones

discovery

• discovery.discover — Runs policy-filtered project discovery for the requesting project.
  • Input accepts requestingProjectId, a text query, topK, and booleans for meta-vector, taxonomy, and relationship participation.
  • Output shape is { discovery, policy, snapshot }.
  • discovery.projectIds are already policy-filtered candidate IDs. Denied candidates contribute only aggregated policy.deniedProjectCount and policy.reasonCodes.
  • snapshot is the requesting project's current knowledge snapshot so the UI does not need a second round trip for freshness and runtime-posture diagnostics.
• discovery.snapshot — Returns the current assembled knowledge snapshot for a project.
  • Response includes meta-vector state, taxonomy assignments, incoming/outgoing relationship edges, the latest refresh record, and diagnostics.runtimePosture.
  • null means the project has no current knowledge-index projection and no in-flight refresh state.
• discovery.refresh — Triggers a manual refresh of one project's canonical knowledge projection.
  • The server supplies trigger: 'manual' and requestedAt.
  • reasonCode defaults to operator_manual_refresh.
  • Output outcome is one of updated, cleared, skipped_no_change, or failed.

marketplace

• marketplace.browsePackages — Returns governed registry browse results for the marketplace surface.
  • Filters support query text, trust tiers, distribution statuses, compatibility states, and pagination.
  • Each item includes package projection data, latest release metadata, optional project-scoped trustEligibility, and deep links for artifact, Projects, and MAO continuity.
• marketplace.getPackageDetail — Returns a package detail snapshot for one package.
  • Response includes package metadata, latest release, release history, maintainer records, governance timeline, appeals, deep links, and optional project-scoped trust-eligibility posture.
  • Throws NOT_FOUND when the package does not exist.
• marketplace.getModerationDashboard — Returns the inspect-first moderation dashboard projection.
  • Input supports free-text query, moderation-status filters, and whether resolved appeals are included.
  • Response includes package rows plus aggregate counts for pending appeals, active holds, and delisted packages.
• marketplace.getDiscoveryFeed — Returns the advisory marketplace nudge feed for one surface.
  • Input identifies the target surface, optional projectId, optional signalRefs, and a limit.
  • Output includes suggestion cards, reasoning, suppression affordances, and trust-eligibility posture derived from canonical registry and nudge-runtime truth.
• marketplace.applyNudgeSuppression — Applies canonical suppression state for a marketplace nudge.
  • Supports candidate, category, project, and global scopes.
  • Returns the persisted suppression record; surfaces should treat this as shared runtime truth rather than as a local preference write.
• marketplace.recordNudgeFeedback — Persists marketplace feed interaction events such as opened, dismissed, or similar feedback signals.
  • The server supplies occurredAt when the caller omits it.
• marketplace.routeNudgeAcceptance — Records acceptance feedback and returns the governed acceptance route.
  • Marketplace-package acceptance currently resolves to runtime_authorization_required, not direct installation.

packages

• packages.prepareAppInstall — Resolves the canonical install contract for an installable app package in one project context.
  • Input fields: project_id, package_id, and optional release_id.
  • Output shape includes package/release identity, declared permissions, grouped config descriptors, supported install stages, and whether an install hook is present.
  • The response is preparation truth only. It does not persist config, store secrets, or materialize a package.
• packages.prepareAppSettings — Resolves the canonical settings contract for one already-installed app package in one project context.
  • Input fields: project_id and package_id.
  • Output shape includes grouped settings descriptors, the current config_version, runtime summary, current secret-state metadata, and the host-safe panel config snapshot used for live convergence.
• packages.installApp — Runs the canonical app-install orchestration for one project-scoped installable app.
  • Input fields: project_id, package_id, optional release_id, actor_id, permissions_approved, config, secrets, oauth, and optional evidence_refs.
  • Output shape includes the preparation snapshot, install status (success, partial, or failed), phase markers, validation results, optional runtime session/config version metadata, stored-secret metadata, rollback posture, and witness references.
  • Secret and OAuth values stay on the vault / credential-install path; non-secret config remains host/runtime truth.
• packages.saveAppSettings — Runs the canonical app-settings orchestration for one installed app package.
  • Input fields: project_id, package_id, actor_id, expected_config_version, non-secret config, secret mutation intents in secrets, and optional evidence_refs.
  • Output shape includes save status (success, partial, or failed), apply_status (applied, reverted, or blocked), phase markers, validation results, the effective runtime/config version, stored-secret metadata, rollback posture, and optional activation failure details.
  • The backend owns the governed deactivate -> update config -> reactivate -> recover flow; hosts stay transport-thin and never become a second config authority.
• packages.listAppPanels — Returns the runtime-owned projection of active manifest-declared app panels for trusted first-party hosts.
  • Each item includes the canonical route_path, host-safe dockview_panel_id, effective config_version, panel label, preserve_state, optional dock position, and the sanitized config_snapshot used by trusted hosts during panel bridge bootstrap.
  • Panels appear here only while an app session is active; manifest declarations alone do not make a panel serveable.
• packages.install — Runs the canonical package install pipeline for one project-scoped package request.
  • Input fields: project_id, package_id, optional requested_version_range, optional release_id, actor_id, optional instance_root, and optional evidence_refs.
  • release_id and requested_version_range are mutually exclusive.
  • Output shape includes the shared resolution result, install journal writes, lifecycle transition results, final status (installed, blocked, or rolled_back), and optional failure details.
  • Canonical installs materialize only into governed package-store roots and fail closed with explicit reason-coded output when dependency resolution, lifecycle gating, or write/rollback handling blocks completion.

Settings procedure examples

packages.prepareAppSettings request:

{
  "project_id": "550e8400-e29b-41d4-a716-446655440802",
  "package_id": "telegram-connector"
}

Response excerpt:

{
  "package_id": "telegram-connector",
  "config_version": "cfg-1",
  "runtime": {
    "status": "active",
    "config_version": "cfg-1"
  },
  "config_groups": [
    {
      "id": "connector",
      "label": "Connector",
      "fields": [
        {
          "key": "bot_token",
          "type": "secret",
          "secret": true,
          "secret_state": {
            "key": "bot_token",
            "configured": true,
            "source": "secret_field"
          }
        }
      ]
    }
  ]
}

packages.saveAppSettings request:

{
  "project_id": "550e8400-e29b-41d4-a716-446655440802",
  "package_id": "telegram-connector",
  "actor_id": "web-marketplace",
  "expected_config_version": "cfg-1",
  "config": {
    "region": "eu"
  },
  "secrets": {
    "bot_token": {
      "operation": "replace",
      "value": "new-token"
    }
  },
  "evidence_refs": []
}

Response excerpt:

{
  "status": "success",
  "apply_status": "applied",
  "phase": "completed",
  "effective_config_version": "cfg-2",
  "runtime": {
    "status": "active",
    "config_version": "cfg-2"
  },
  "rollback_applied": false
}

config

• config.update — Applies non-secret system configuration changes. Vault-backed provider credentials, available-model enumeration, and saved model selections are managed through preferences.*.

preferences

• preferences.getApiKeys — Returns masked vault-backed provider-key state. Raw API keys are never returned to the client.
• preferences.setApiKey — Stores the provider key in the credential vault, updates the active runtime immediately, registers the remote provider, and updates provider routing without requiring a restart.
• preferences.deleteApiKey — Revokes the stored provider key, removes the provider from active routing, and cleans the provider/config state. If no cloud providers remain, runtime falls back to local-only routing posture.
• preferences.testApiKey — Validates the supplied key when present; otherwise it tests the already-stored vault key. Returns { valid: false, error: 'No API key configured for this provider. Store a key first.' } when nothing is available to test.
• preferences.getAvailableModels — Returns the combined local Ollama model list plus cloud models discovered dynamically from the Anthropic and OpenAI /v1/models APIs. Successful API responses are cached in-memory with a 5-minute TTL. Providers without a stored API key are skipped. When an API call fails, a minimal static fallback list is returned with a staleness indicator.
• preferences.getModelSelection / preferences.setModelSelection — Persist the separate Principal and System model selections that Nous restores on startup. setModelSelection accepts cloud specs and ollama:* specs, then updates the in-memory provider config and reasoner assignment immediately so model changes take effect without a restart. Invalid model specs are rejected gracefully without corrupting provider state.
• preferences.getRoleAssignments / preferences.setRoleAssignment — Read and update the runtime provider assignment for every ModelRole (orchestrator, reasoner, tool-advisor, summarizer, embedder, reranker, vision). setRoleAssignment accepts the same provider:model spec format as setModelSelection, including local Ollama models.
• preferences.getSystemStatus — Returns current Ollama posture, configured cloud providers, and whether the credential-vault surface is healthy.

opctl

• submitCommand — Submit a control command. For T1+ actions, include confirmationProof from requestConfirmationProof.
• requestConfirmationProof — Request a runtime-issued, short-lived proof for T1/T2/T3 actions.
• hasStartLock — Check if project has start lock (hard_stopped).
• getProjectControlState — Get project control state for MAO-007 gating (running, paused_review, hard_stopped, resuming).

mao

• getAgentProjections — Agent projections for a project (derived from canonical event/state truth).
• getProjectControlProjection — Project control projection (pause/resume/hard-stop status, Cortex review, and optional voice_projection for current turn state, degraded mode, pending confirmation, and continuation posture).

voice

• voice.beginTurn — Creates canonical turn state for a voice session and initializes session projection posture.
• voice.evaluateTurn — Evaluates combined handoff signals, risky intent posture, degraded mode, and confirmation requirements through the canonical runtime.
• voice.registerAssistantOutput — Registers assistant speech state so later interruption and continuation behavior stays canonical.
• voice.handleBargeIn — Stops active output, records interruption latency, and forces continuation-required posture.
• voice.resolveContinuation — Records explicit continuation outcome after interruption; does not auto-resume.
• voice.getSessionProjection — Returns canonical voice session state for web, MAO, and mobile consumers.

mobile

• operationsSnapshot — Returns the aggregated mobile operations projection for a project. This combines canonical project, escalation, voice, and endpoint-trust summaries for the mobile web surface without creating a second authority model.

gtm

• computeGateReport — Compute GTM gate report (CFPC, ABPR, promotion_blocked) from verification report, pillar status, benchmark results.

health

• health.check — Returns the legacy component health report. Backward-compatible; unchanged by the health monitoring feature.
• health.systemStatus — Returns the current system status snapshot including boot status, gateway health projection, and system context projection. Sourced from the HealthAggregator in-memory cache (synchronous, no I/O).
• health.providerHealth — Returns the current provider health snapshot listing all configured model providers with their status and configuration metadata. Provider status defaults to unknown until active probing is implemented.
• health.agentStatus — Returns the current agent status snapshot with per-agent-class health projections derived from the gateway runtime.

firstRun

witness