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.
WelcomeFireResult (discriminated union on welcomeFired)
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.
chat.fireWelcomeIfUnsent — Fires the one-shot welcome message into the principal chat if the persisted agent.welcomeMessageSent flag is currently false. The mutation reads the flag, returns { welcomeFired: false, reason: 'already_sent' } when already set; otherwise composes a single agent turn through the runtime's existing prompt path (gatewayRuntime.handleChatTurn) using a short preset-neutral seed fragment, manually appends only the assistant entry to the chat's short-term-memory store (so the seed is never persisted as a user-role turn), then sets welcomeMessageSent = true. The discriminated return is { welcomeFired: true, traceId } on success or { welcomeFired: false, reason } on failure, where reason is one of 'already_sent' | 'composition_error' | 'empty_response' | 'stm_append_error' | 'no_project_id'. Set-after-emit ordering: the flag is set only after the composer returns a non-empty response and the STM append succeeds, so a transient provider failure leaves the flag false and the next chat panel mount retries the welcome. The renderer trigger lives in DesktopChatPanel's mount effect (single call site, mount-once via useRef guard); the welcome appears in the chat as a normal agent message with no special metadata, no badge, and no UI affordance — the same row component renders it as every subsequent agent turn. See Chat § Welcome Message (First Open) for the user-facing lifecycle.
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.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.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.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.
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.
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.
config.update — Applies non-secret system configuration changes. Vault-backed provider credentials, available-model enumeration, and saved model selections are managed through preferences.*.
ApiKeyProviderKey is a registry-derived provider vendor key for a certified provider whose definition declares API-key auth metadata, for example anthropic or openai.
preferences.getApiKeys — Returns masked vault-backed provider-key state for registry-defined API-key providers. 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 remote API 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. The test request is driven by the provider definition and prefers healthCheckEndpoint, falling back to modelListEndpoint. Returns { valid: false, error: 'No API key configured for this provider. Store a key first.' } when nothing is available to test.
preferences.getAvailableModels — Returns available models from registry-defined provider metadata. Remote API providers are discovered when they declare modelListEndpoint/modelListFormat and have a stored key; successful remote responses are cached in-memory with a 5-minute TTL. Local providers that declare model discovery, such as Ollama, use their configured endpoint and bypass the remote cache. Providers without a required key are skipped. When discovery fails, the provider's defaultModelId is returned as an unavailable fallback.
preferences.getModelSelection / preferences.setModelSelection — Persist the separate Principal and System model selections that Nous restores on startup. setModelSelection accepts remote API specs and ollama:* specs, then updates the in-memory provider config and model role 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 (cortex-chat, cortex-system, orchestrators, workers). 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.
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).
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.
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.checkPrerequisites — Returns the wizard's prerequisite snapshot used to render the Model Download step: detected hardware, the recommended local model(s) for that hardware, the Ollama daemon health probe, and a validation: Record<string, ValidationState> map keyed by modelSpec for every recommended model. The map is assembled by calling the runtime availability helper for each unique recommendation in parallel; per-call info-level log: [nous:first-run] validation map: <n> validated, <m> unavailable, <k> offline. Renderer reads the map with a graceful-degradation fallback of 'pending' when the field or key is absent, so historic clients that pre-date the validation extension continue to render correctly.
firstRun.validateModelAvailability — Standalone availability check used by the Model Download step's custom-spec input. Takes { modelSpec: z.string().min(1) }, returns { modelSpec, state } where state is one of 'validated' | 'pending' | 'unavailable' | 'offline'. Performs a two-stage check: (a) inline well-formedness of the spec — empty, malformed, or non-ollama: specs return 'unavailable' with no network call; (b) anonymous HEAD https://ollama.com/library/<modelId> with Accept: */*, User-Agent: Nous/<version>, no body, no cookies, and a 3-second AbortSignal.timeout deadline. Mapping: 2xx → 'validated', 404 → 'unavailable', timeout / DNS / network / 5xx → 'offline'. No PII is sent: no OS, architecture, CPU, GPU, user identifier, session identifier, or device identifier appears in the request. Reuses the same 30-minute per-spec session cache as checkPrerequisites.
firstRun.writeIdentity — Writes the agent identity step payload to nous-config.json5 via the three agent block writers (setAgentName, setPersonalityConfig, setUserProfile) and then marks 'agent_identity' complete in the wizard state. All three input fields (name, personality, profile) are required — the input schema is .strict() and rejects partial submissions before reaching the writers. Input shape is JSON-serializable (no Date, Map, Set, or function values) per the desktop wizard's raw-fetch transport constraint. Sibling preservation across the agent.* block is a property of the underlying writers when driven individually (e.g. by hand-edits or future per-field procedures); it is not surfaced through firstRun.writeIdentity, which accepts only the full identity-step payload as a single batched submission per SP 1.3 (Decisions 3 + 7). The wizard UI that submits this payload is the first-run Identity step (WizardStepIdentity).
firstRun.resetWizard — Resets the first-run wizard. Clears the entire agent block via clearAgentBlock and then resets wizard state via resetFirstRunState. Leaves providers and modelRoleAssignments untouched. After reset, the agent-block readers return their typed defaults ("Nous", { preset: "balanced" }, {}, false) and the wizard restarts from the first step. Because the cleared agent block includes welcomeMessageSent, the next time the principal chat panel mounts after firstRun.resetWizard the agent emits a fresh welcome message — re-arming the one-shot welcome (see chat.fireWelcomeIfUnsent) is part of the reset semantic.
ValidationState is the Zod enum 'validated' | 'pending' | 'unavailable' | 'offline' exported from @nous/shared-server. It describes whether the public Ollama library currently lists a given modelSpec. The wizard renderer maps each state to a per-card visual indicator (dot color + accessible label) on the Model Download step; see First Run § The Model Download Step for the user-facing semantics.