@agent-compose/sdk 0.6.0 → 0.8.0

package/src/directives.ts

@@ -0,0 +1,184 @@
+/**
+ * Cloud-session UI directives — the typed marker contract between the
+ * `agentc` CLI running INSIDE a cloud session's sandbox and the server's
+ * cloud executor.
+ *
+ * A converged cloud session drives a coding CLI whose only platform surface
+ * is `agentc` invoked over Bash — it has no typed platform tools, so it
+ * could never produce the transcript parts the dashboard renders as rich
+ * cards (`get_run_changes` → the inline diff reviewer) or acts on
+ * (`navigate_dashboard` → armed-tab navigation). The bridge:
+ *
+ *   1. `agentc navigate|display …` PRINTS one marker line to stdout —
+ *      `[[ac:directive:v1 {"kind":…}]]` — and nothing else happens locally.
+ *   2. The marker rides back to the server inside the streamed tool_result
+ *      (the coding CLI echoes the command's output).
+ *   3. The cloud executor scans TOOL RESULTS (never model text) for
+ *      markers, executes each directive server-side through the SAME
+ *      platform tool executors a platform turn uses (validation, factory
+ *      gating, result shapes all identical), and persists the resulting
+ *      tool_call + tool_result pair into the transcript.
+ *   4. Existing consumers act unchanged: the dashboard's diff-card /
+ *      run-card renderers key on tool names, and navigation stays gated by
+ *      the requesting tab's armed window + client-side URL re-validation.
+ *
+ * The kind set is CLOSED, but no longer purely read-only. `ask` is the ONE
+ * write-bearing directive: it inserts a bounded mentions row as the session
+ * owner (who could ping the same member from the dashboard anyway) and
+ * persists an ask card. Everything else stays read-scope — run lookups,
+ * change-set listing, server-gated file reads (preview / table_file /
+ * file_diff), or the navigate directive (validated URL, acted on
+ * client-side, cannot submit anything). Markers are data in untrusted
+ * output — the parser is hostile-input safe and hard-capped.
+ */
+
+/** Marker frame. v1 is part of the prefix: unknown future versions parse
+ *  as no-match (fail closed) rather than as a v1 directive. */
+export const DIRECTIVE_MARKER_PREFIX = "[[ac:directive:v1 ";
+export const DIRECTIVE_MARKER_SUFFIX = "]]";
+
+/** Max directives honoured per tool result — one command emits one marker;
+ *  anything past this in a single output is echo/noise, not intent. */
+export const MAX_DIRECTIVES_PER_OUTPUT = 4;
+
+export type CloudDirective =
+  /** Take the requesting user's dashboard tab to a relative page. */
+  | { kind: "navigate"; url: string }
+  /** Render one run's detail into the transcript (`get_run` shape). */
+  | { kind: "run"; runId: string; workflow?: string }
+  /** Render one run's change-set — the dashboard's inline diff reviewer
+   *  (`get_run_changes` shape). */
+  | { kind: "run_changes"; runId: string; workflow?: string }
+  /** Sandboxed inline HTML preview of a drive file, frozen (and size-capped)
+   *  server-side at display time (`display_preview` shape). */
+  | { kind: "preview"; path: string }
+  /** Sortable table card sourced from a drive .csv/.json file, read and
+   *  capped server-side (`display_table` shape). */
+  | { kind: "table_file"; path: string }
+  /** File-level revision diff card; selectors resolve against
+   *  `factory_file_revisions` server-side (`display_diff` shape). */
+  | { kind: "file_diff"; path: string; from: string; to: string }
+  /** Interactive question card gated on a named approver — resolution and
+   *  the mentions ping are server-authoritative (`display_ask` shape). The
+   *  one write-bearing directive (see the module header). */
+  | { kind: "ask"; prompt: string; approver: string; options?: Array<{ id: string; label: string }> };
+
+/** `runId` values the run directives accept: a UUID, or the literal
+ *  `latest` (resolved server-side against the session's factory, optionally
+ *  narrowed by `workflow`). */
+const RUN_ID_RE = /^(latest|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})$/i;
+
+/** Revision selectors the `file_diff` directive accepts: a literal
+ *  `factory_file_revisions.id`, `head`, `prev`, or `head~N` (N ≤ 999).
+ *  Exported so the CLI validates with the same rule it emits under. */
+export const REVISION_SELECTOR_RE = /^(\d{1,12}|head|prev|head~[1-9]\d{0,2})$/;
+
+/** Drive-path bound shared by the path-bearing directive kinds. */
+const DIRECTIVE_PATH_MAX = 512;
+
+/** Ask directive bounds — tighter than the promoter-path ask marker, sized
+ *  to fit the 1024-char directive body. */
+export const ASK_DIRECTIVE_PROMPT_MAX = 500;
+export const ASK_DIRECTIVE_MAX_OPTIONS = 6;
+export const ASK_DIRECTIVE_OPTION_ID_MAX = 50;
+export const ASK_DIRECTIVE_OPTION_LABEL_MAX = 60;
+export const ASK_APPROVER_MIN = 3;
+export const ASK_APPROVER_MAX = 320;
+
+function validDirectivePath(v: unknown): string | null {
+  return typeof v === "string" && v.length >= 1 && v.length <= DIRECTIVE_PATH_MAX ? v : null;
+}
+
+/** One marker line for `agentc` to print. */
+export function renderDirectiveMarker(directive: CloudDirective): string {
+  return `${DIRECTIVE_MARKER_PREFIX}${JSON.stringify(directive)}${DIRECTIVE_MARKER_SUFFIX}`;
+}
+
+function validDirective(value: unknown): CloudDirective | null {
+  if (typeof value !== "object" || value === null) return null;
+  const d = value as Record<string, unknown>;
+  if (d.kind === "navigate") {
+    const url = d.url;
+    if (typeof url !== "string" || url.length === 0 || url.length > 400) return null;
+    // Relative-only at the contract layer; the navigate tool re-validates
+    // against the site map and the dashboard validates a third time.
+    if (!url.startsWith("/") || url.startsWith("//")) return null;
+    return { kind: "navigate", url };
+  }
+  if (d.kind === "run" || d.kind === "run_changes") {
+    const runId = d.runId;
+    if (typeof runId !== "string" || !RUN_ID_RE.test(runId)) return null;
+    const workflow = d.workflow;
+    if (workflow !== undefined && (typeof workflow !== "string" || workflow.length === 0 || workflow.length > 255)) {
+      return null;
+    }
+    return { kind: d.kind, runId, ...(workflow !== undefined ? { workflow } : {}) };
+  }
+  if (d.kind === "preview" || d.kind === "table_file") {
+    const path = validDirectivePath(d.path);
+    if (!path) return null;
+    if (d.kind === "table_file" && !/\.(csv|json)$/i.test(path)) return null;
+    return { kind: d.kind, path };
+  }
+  if (d.kind === "file_diff") {
+    const path = validDirectivePath(d.path);
+    if (!path) return null;
+    const { from, to } = d;
+    if (typeof from !== "string" || !REVISION_SELECTOR_RE.test(from)) return null;
+    if (typeof to !== "string" || !REVISION_SELECTOR_RE.test(to)) return null;
+    return { kind: "file_diff", path, from, to };
+  }
+  if (d.kind === "ask") {
+    const { prompt, approver } = d;
+    if (typeof prompt !== "string" || prompt.length < 1 || prompt.length > ASK_DIRECTIVE_PROMPT_MAX) return null;
+    if (typeof approver !== "string" || approver.length < ASK_APPROVER_MIN || approver.length > ASK_APPROVER_MAX) {
+      return null;
+    }
+    let options: Array<{ id: string; label: string }> | undefined;
+    if (d.options !== undefined) {
+      if (!Array.isArray(d.options) || d.options.length === 0 || d.options.length > ASK_DIRECTIVE_MAX_OPTIONS) {
+        return null;
+      }
+      options = [];
+      for (const raw of d.options) {
+        if (typeof raw !== "object" || raw === null) return null;
+        const { id, label } = raw as { id?: unknown; label?: unknown };
+        if (typeof id !== "string" || id.length < 1 || id.length > ASK_DIRECTIVE_OPTION_ID_MAX) return null;
+        if (typeof label !== "string" || label.length < 1 || label.length > ASK_DIRECTIVE_OPTION_LABEL_MAX) {
+          return null;
+        }
+        options.push({ id, label });
+      }
+    }
+    return { kind: "ask", prompt, approver, ...(options !== undefined ? { options } : {}) };
+  }
+  return null;
+}
+
+/**
+ * Extract every valid v1 directive from one command output. Hostile-input
+ * safe: malformed JSON, unknown kinds, oversized fields, and unterminated
+ * markers are skipped silently; at most MAX_DIRECTIVES_PER_OUTPUT come
+ * back. Never throws.
+ */
+export function parseDirectiveMarkers(text: string): CloudDirective[] {
+  const out: CloudDirective[] = [];
+  let from = 0;
+  while (out.length < MAX_DIRECTIVES_PER_OUTPUT) {
+    const start = text.indexOf(DIRECTIVE_MARKER_PREFIX, from);
+    if (start < 0) break;
+    const bodyStart = start + DIRECTIVE_MARKER_PREFIX.length;
+    const end = text.indexOf(DIRECTIVE_MARKER_SUFFIX, bodyStart);
+    if (end < 0) break;
+    from = end + DIRECTIVE_MARKER_SUFFIX.length;
+    const body = text.slice(bodyStart, end);
+    if (body.length > 1_024) continue;
+    try {
+      const directive = validDirective(JSON.parse(body));
+      if (directive) out.push(directive);
+    } catch {
+      // malformed JSON in a marker frame — echo/noise, skip
+    }
+  }
+  return out;
+}