@noir-ai/daemon 1.0.0-beta.1 → 1.2.0-beta.1

package/dist/index.d.ts

@@ -2,11 +2,96 @@ import { EmbedderConfig, ContextEngine, EmbedFn } from '@noir-ai/context';
 export { ContextStatus } from '@noir-ai/context';
 import { ProjectId, ProjectInfo } from '@noir-ai/core';
 import { Store } from '@noir-ai/store';
+import { IntegrationDeclaration } from '@noir-ai/skills';
 import { MemoryConfig, MemoryEngine } from '@noir-ai/memory';
 import { ResolvedModelConfig } from '@noir-ai/model';
 import { McpServer } from '@modelcontextprotocol/server';
 import { WorkflowEngine, Phase, WorkflowState, Mode, GateResult } from '@noir-ai/workflow';
 
+/** Op-shaped error thrown when input violates the contract (bad id, missing
+ *  required field, unknown op). The handler maps it to `{ok:false, reason:'invalid-op'}`. */
+declare class InvalidOp extends Error {
+    constructor(message: string);
+}
+type ClickUpOp = 'status' | 'subtask' | 'comment' | 'batch';
+/** Workspace binding the proxy resolves listId/teamId from (config > payload). */
+interface ClickUpBinding {
+    teamId?: string;
+    listId?: string;
+}
+/** A constructed HTTP request against an allowlisted endpoint. The auth header
+ *  is ABSENT here — it is added at execute time only; the dry-run preview shows
+ *  a redacted placeholder so the token never leaves the execute path. */
+interface BuiltRequest {
+    method: 'GET' | 'POST' | 'PUT';
+    /** Full allowlisted URL (constructed from op + payload + binding). */
+    url: string;
+    /** JSON body (already stringified-safe as an object). */
+    body?: Record<string, unknown>;
+    /** Stable descriptor for the audit `target` field (e.g. `task/abc123`). */
+    target: string;
+}
+/** A single preview/result row. */
+interface RequestRow {
+    method: string;
+    url: string;
+    body?: Record<string, unknown>;
+    /** Redacted auth header for the preview (always `pk_***`). */
+    auth: 'pk_***';
+    target: string;
+}
+/** A normalized task for the batch op (H2 markdown + the `tasks[]` array both
+ *  reduce to this). All fields are JSON DATA in the POST body — adversary text
+ *  in a task title becomes the `name` string, never an executable instruction. */
+interface NormalizedTask {
+    name: string;
+    description?: string;
+    tags?: string[];
+    assignees?: number[];
+    status?: string;
+}
+/** Parse H2-per-task markdown into normalized tasks. Each `## <title>` opens a
+ *  task; body lines until the next `## ` are the description, EXCEPT lines that
+ *  match `- key: value` which are folded into structured fields (assignees/tags).
+ *  Tolerant: a missing leading H2 still yields the body as one task (named from
+ *  the first non-empty line) so a slightly-malformed template still previews. */
+declare function parseH2Tasks(markdown: string): NormalizedTask[];
+/** Build ALL requests an op renders, WITHOUT touching the network. Used by both
+ *  the dry-run preview (no auth) and the execute path (auth added). Throws
+ *  `InvalidOp` on a contract violation (bad id, missing field, unknown op). */
+declare function buildRequests(opRaw: string, payload: Record<string, unknown>, binding: ClickUpBinding): {
+    op: ClickUpOp;
+    requests: BuiltRequest[];
+};
+/** Render a dry-run preview row set. NO auth header, NO network — the token
+ *  never enters this path. */
+declare function previewRows(requests: BuiltRequest[]): RequestRow[];
+/** Minimal fetch shape the proxy needs. Bound to global `fetch` in production;
+ *  a spy in tests (cassette). */
+type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+interface ExecResult {
+    target: string;
+    method: string;
+    url: string;
+    httpStatus: number;
+    success: boolean;
+    /** ClickUp's parsed JSON body (or `{}` when absent). NEVER contains the token
+     *  (ClickUp never echoes it). */
+    response: Record<string, unknown>;
+    /** Present when a 429 backoff fired on this request. */
+    rateLimitedWaitMs?: number;
+    /** For `subtask` with a status follow-up: the new subtask id resolved from the
+     *  create response so the host can reference it. */
+    newTaskId?: string;
+    /** Error message on a non-2xx / network failure (NEVER includes the token). */
+    error?: string;
+}
+/** Execute an op's requests against ClickUp. The `subtask` op is special: its
+ *  optional status follow-up needs the create response's `id`, so the two
+ *  requests run sequentially with the id threaded through. `batch` runs with a
+ *  concurrency cap of 4 + per-request 429 backoff. */
+declare function executeOp(op: ClickUpOp, requests: BuiltRequest[], token: string, fetchImpl: FetchLike): Promise<ExecResult[]>;
+
 /**
  * Build the daemon's {@link ContextEngine} from its already-open store handle
  * + the project `root` + `projectId` + a resolved {@link EmbedderConfig}.
@@ -64,6 +149,141 @@ interface RunningDaemon {
 }
 declare function startHttpServer(opts: StartHttpOptions): Promise<RunningDaemon>;
 
+/**
+ * Per-integration binding resolved at the seam: the shipped declaration (source
+ * of truth for `auth.tokenEnv` + `runtime`) merged with the user's
+ * `integrations.<name>` config overlay (source of truth for `teamId`/`listId`/
+ * `spaceId` + a local `auth.tokenEnv` override / `runtime` downgrade). The
+ * declaration is authoritative for `tokenEnv` unless the config explicitly
+ * overrides it (a workspace that renamed the env var).
+ */
+interface IntegrationBinding {
+    /** Full declaration name, e.g. `'noir-clickup'`. */
+    name: string;
+    /** Short name — declaration name with the `noir-` namespace stripped
+     *  (`'clickup'`). The `noir.clickup_write` tool segment + the documented
+     *  `integrations.clickup.*` config key both use this form. */
+    shortName: string;
+    declaration: IntegrationDeclaration;
+    /** Resolved token env-var name (config override > declaration). */
+    tokenEnv: string;
+    /** Effective runtime tier: the user's `integrations.<name>.runtime` overlay
+     *  wins when set, else the declaration's `runtime`. The daemon gates write-tool
+     *  registration on THIS (not the declaration's) so a local downgrade to `none`
+     *  actually takes the write tool off — the tier model: `none` = skill-side
+     *  reads only, `integrations_auth` still resolves the token. */
+    effectiveRuntime: IntegrationDeclaration['runtime'];
+    teamId?: string;
+    listId?: string;
+    spaceId?: string;
+}
+/**
+ * The per-serve-lifecycle integration handle. Built once (mirrors the store +
+ * workflow + memory engines) and reused across every MCP request. Carries the
+ * discovered declarations merged with the user config so the tools never re-read
+ * the filesystem per call.
+ */
+interface IntegrationService {
+    /** Project root — the anchor for `.noir/audit/` writes. */
+    root: string;
+    /** Bindings keyed by BOTH the full name (`noir-clickup`) and the short name
+     *  (`clickup`) so a tool/config using either form resolves the same binding. */
+    bindings: Map<string, IntegrationBinding>;
+}
+/** Strip the `noir-` namespace prefix from a declaration name. The short form
+ *  is what the `noir.<short>_write` tool segment + the `integrations.<short>`
+ *  config key use; the declaration itself always carries the full `noir-` name. */
+declare function shortNameOf(name: string): string;
+/**
+ * Build the integration service for one serve lifecycle. Discovery is
+ * best-effort: a missing/unreadable skills pack ⇒ an empty service (the tools
+ * degrade gracefully — `integrations_auth` still resolves a caller `envVar`;
+ * `noir.clickup_write` is simply not registered). Never throws.
+ *
+ * @param root project root (`.noir/audit/` anchor)
+ * @param configIntegrations the parsed `integrations` block from `.noir/config.yml`
+ *   (`{ [name]: { auth?, runtime, teamId?, listId?, spaceId? } }`). Keys may use
+ *   either the full `noir-clickup` or the short `clickup` form.
+ */
+declare function buildIntegrationService(root: string, configIntegrations?: Record<string, {
+    auth?: {
+        tokenEnv?: string;
+    };
+    runtime?: 'none' | 'gated-write-proxy' | 'mcp-stdio' | 'external-mcp';
+    teamId?: string;
+    listId?: string;
+    spaceId?: string;
+}>): IntegrationService;
+/** Look up a binding by either the full or short name. */
+declare function findBinding(svc: IntegrationService, name: string): IntegrationBinding | undefined;
+/** Result of a token resolution attempt. */
+type TokenResolution = {
+    ok: true;
+    token: string;
+    envVar: string;
+} | {
+    ok: false;
+    reason: 'no-token';
+    envVar: string;
+} | {
+    ok: false;
+    reason: 'unknown-integration';
+    integration: string;
+};
+/**
+ * Resolve an integration token VALUE from `process.env` at CALL TIME (never at
+ * load time; never cached beyond the call). The token is returned to the calling
+ * agent in the tool result (trusted host) + travels in the outbound
+ * `Authorization` header — and NOWHERE else (no stderr, no audit body).
+ *
+ * Two call shapes:
+ *   - `{ integration: 'noir-clickup' }` → look up `tokenEnv` from the discovered
+ *     declaration (config override honored), then read `process.env[tokenEnv]`.
+ *   - `{ envVar: 'CLICKUP_API_TOKEN' }` → read `process.env[envVar]` directly.
+ */
+declare function resolveToken(svc: IntegrationService, opts: {
+    integration?: string;
+    envVar?: string;
+}, env?: NodeJS.ProcessEnv): TokenResolution;
+/** One executed-write audit record (X-T3, X-OQ2). Append-only JSONL — one line
+ *  per executed write. Dry-runs are NOT audited (no write happened). */
+interface IntegrationAuditEntry {
+    /** Fixed discriminator so a future `.noir/audit/` reader can filter mixed
+     *  gate (`kind:'gate'`-ish) + integration rows. */
+    kind: 'integration';
+    /** Declaration name, e.g. `'noir-clickup'`. */
+    integration: string;
+    /** Op verb (normalized short form): `status` | `subtask` | `comment` | `batch`. */
+    op: string;
+    /** Stable target descriptor (e.g. `'task/abc123'`, `'list/90125/task'`). */
+    target: string;
+    /** HTTP method on the allowlisted endpoint. */
+    method: string;
+    /** HTTP status returned by ClickUp (last attempt after 429 backoff). */
+    httpStatus: number;
+    /** True iff `httpStatus` is 2xx. */
+    success: boolean;
+    /** Epoch-millis when the write was attempted. */
+    timestamp: number;
+    /** Present when a 429 backoff fired (the spec calls for recording the wait). */
+    rateLimitedWaitMs?: number;
+    /** Error message when `success === false` (NEVER includes the token). */
+    error?: string;
+}
+/**
+ * Append one integration audit record to `.noir/audit/integration-<short>.jsonl`
+ * (the SAME `.noir/audit/` dir as the S4 gate export — X-OQ2 resolved: REUSE).
+ * Append-only JSONL so concurrent/sequential writes don't clobber each other and
+ * the file grows linearly with executed writes. Creates the dir if missing.
+ *
+ * Propagates filesystem errors to the caller — the gated proxy's handler is the
+ * best-effort boundary: it catches, sets the result envelope's `audited:false`,
+ * and continues (the ClickUp write already happened; an audit failure does NOT
+ * roll it back). Keeping the throw honest makes `audited:false` reachable instead
+ * of a perpetually-true flag.
+ */
+declare function writeIntegrationAudit(root: string, integrationName: string, entry: IntegrationAuditEntry): void;
+
 interface DaemonRecord {
     pid: number;
     port: number;
@@ -248,6 +468,20 @@ interface ServerContext {
      * the flag + the engine agree by construction.
      */
     memoryConsolidation?: boolean;
+    /**
+     * Optional integration service (slice X — X-T3). Built once per serve
+     * lifecycle from the discovered `integration.json` declarations
+     * (@noir-ai/skills `discoverIntegrations`) merged with the user's
+     * `integrations:<name>` config block. When present, the `integrations_auth`
+     * tool is ALWAYS registered (resolves a token by env var at call time — kills
+     * the non-interactive-shell gotcha), and `noir.clickup_write` is registered
+     * when a `noir-clickup` declaration with `runtime:'gated-write-proxy'` is
+     * discovered. Both tools degrade gracefully (`no-token`/`no-config`) when the
+     * binding/env is absent — never a crash. Token values NEVER enter stderr or
+     * audit bodies (only the tool RESULT to the trusted host + the outbound
+     * `Authorization` header).
+     */
+    integrations?: IntegrationService;
 }
 /** JSON returned by the `store_status` tool. */
 interface StoreStatus {
@@ -321,4 +555,4 @@ declare function openStoreForDaemon(projectId: ProjectId, root: string): Promise
  */
 declare function buildWorkflowEngine(store: Store, root: string, projectId: ProjectId): WorkflowEngine;
 
-export { type DaemonRecord, type DaemonStore, type EnsureResult, type HostStatus, type RunningDaemon, type ServerContext, type StartHttpOptions, type StatusContext, type StoreStatus, type Transport, type WorkflowStatus, buildContextEngine, buildMemoryEngine, buildStatus, buildWorkflowEngine, clearDaemonRecord, createNoirServer, daemonJsonPath, ensureDaemonRunning, noirHome, openStoreForDaemon, pidAlive, readDaemonRecord, resolveConsolidationCapability, resolveMemoryConsolidation, startHttpServer, startStdioServer, writeDaemonRecord };
+export { type DaemonRecord, type DaemonStore, type EnsureResult, type HostStatus, type IntegrationAuditEntry, type IntegrationBinding, type IntegrationService, InvalidOp, type RunningDaemon, type ServerContext, type StartHttpOptions, type StatusContext, type StoreStatus, type Transport, type WorkflowStatus, buildContextEngine, buildIntegrationService, buildMemoryEngine, buildRequests, buildStatus, buildWorkflowEngine, clearDaemonRecord, createNoirServer, daemonJsonPath, ensureDaemonRunning, executeOp, findBinding, noirHome, openStoreForDaemon, parseH2Tasks, pidAlive, previewRows, readDaemonRecord, resolveConsolidationCapability, resolveMemoryConsolidation, resolveToken, shortNameOf, startHttpServer, startStdioServer, writeDaemonRecord, writeIntegrationAudit };