akanjs 3.0.0-alpha.2 → 3.0.0-alpha.21

package/vendor/use-agentic/AgenticSurface.ts

@@ -0,0 +1,294 @@
+import type {
+  PublishedResource,
+  PublishedTool,
+  ResourceDiff,
+  ResourceEntry,
+  ScopeEntry,
+  SurfaceSnapshot,
+  SurfaceSource,
+  SurfaceView,
+  ToolEntry,
+} from "./types";
+
+const SHARED_KEY = Symbol.for("useAgentic.sharedSurface");
+
+/**
+ * The live registry of what the mounted screen offers an agent: tools, readable resources, and scopes.
+ *
+ * Entries come and go with component lifetimes, so unlike a static catalogue this is subscribable and every
+ * snapshot answers "now". A registration stack backs each name — remounts are ordinary React behavior, so a
+ * duplicate name warns and the newest wins instead of throwing, and unregistering restores what it shadowed.
+ */
+export class AgenticSurface {
+  /** One surface per runtime unless a provider isolates its own. Keyed on `globalThis` so duplicated module copies still meet. */
+  static get shared(): AgenticSurface {
+    const holder = globalThis as typeof globalThis & { [SHARED_KEY]?: AgenticSurface };
+    holder[SHARED_KEY] ??= new AgenticSurface();
+    return holder[SHARED_KEY];
+  }
+
+  /** MCP tool names allow `[A-Za-z0-9_.-]`, and `.` is the scope join — so every part is folded into `[A-Za-z0-9_-]`. */
+  static sanitize(part: string) {
+    return part.replace(/[^A-Za-z0-9_-]/g, "-");
+  }
+
+  static childPath(parent: string[], id: string) {
+    return [...parent, AgenticSurface.sanitize(id)];
+  }
+
+  static fullName(scope: string[], name: string) {
+    return [...scope.map((part) => AgenticSurface.sanitize(part)), AgenticSurface.sanitize(name)].join(".");
+  }
+
+  #tools = new Map<string, ToolEntry[]>();
+  #resources = new Map<string, ResourceEntry[]>();
+  #scopes = new Map<string, ScopeEntry[]>();
+  #guides: { scope: string; text: string }[] = [];
+  #sources = new Set<SurfaceSource>();
+  #listeners = new Set<() => void>();
+  #warned = new Set<string>();
+
+  subscribe(listener: () => void) {
+    this.#listeners.add(listener);
+    return () => {
+      this.#listeners.delete(listener);
+    };
+  }
+
+  registerTool(scope: string[], entry: ToolEntry) {
+    return this.#stack(this.#tools, AgenticSurface.fullName(scope, entry.name), entry);
+  }
+
+  registerResource(scope: string[], entry: ResourceEntry) {
+    return this.#stack(this.#resources, AgenticSurface.fullName(scope, entry.name), entry);
+  }
+
+  openScope(parent: string[], scope: ScopeEntry) {
+    return this.#stack(this.#scopes, AgenticSurface.childPath(parent, scope.id).join("."), scope);
+  }
+
+  /**
+   * Standing guidance for the agent while the registrant is mounted — instructions, not context data. Kept in
+   * registration order rather than sorted: guides are prose, and each one must stay a coherent block.
+   */
+  registerGuide(scope: string[], text: string) {
+    const entry = { scope: scope.join("."), text };
+    this.#guides.push(entry);
+    this.#notify();
+    return () => {
+      const idx = this.#guides.indexOf(entry);
+      if (idx >= 0) this.#guides.splice(idx, 1);
+      this.#notify();
+    };
+  }
+
+  addSource(source: SurfaceSource) {
+    this.#sources.add(source);
+    const unsubscribe = source.subscribe?.(() => this.#notify());
+    this.#notify();
+    return () => {
+      this.#sources.delete(source);
+      unsubscribe?.();
+      this.#notify();
+    };
+  }
+
+  snapshot(view: string[] = []): SurfaceSnapshot {
+    const viewKey = view.join(".");
+    const tools = [...this.#activeTools(view)].map(([name, entry]) => AgenticSurface.#publishTool(name, entry));
+    const resources = [...this.#activeResources(view)].map(([name, entry]) =>
+      AgenticSurface.#publishResource(name, entry),
+    );
+    const scopes = [...this.#scopes.entries()]
+      .filter(([path]) => AgenticSurface.#within(viewKey, path))
+      .map(([path, stack]) => {
+        const scope = stack[stack.length - 1];
+        return { path, ...(scope.label ? { label: scope.label } : {}), ...(scope.kind ? { kind: scope.kind } : {}) };
+      });
+    
+    return {
+      tools: tools.sort((a, b) => (a.name < b.name ? -1 : 1)),
+      resources: resources.sort((a, b) => (a.name < b.name ? -1 : 1)),
+      scopes: scopes.sort((a, b) => (a.path < b.path ? -1 : 1)),
+      guides: this.#guides.filter((guide) => AgenticSurface.#guideApplies(viewKey, guide.scope)).map((g) => g.text),
+    };
+  }
+
+  /**
+   * A zone session's reading half: the same registry filtered to one scope subtree. Hook entries filter by their
+   * scope-prefixed name, sources decide for themselves per view, and guides follow the layout cascade — a zone
+   * reads its ancestors' guidance plus its own, never a sibling's. The empty path is the surface itself.
+   */
+  view(path: string[]): SurfaceView {
+    if (!path.length) return this;
+    return {
+      snapshot: () => this.snapshot(path),
+      tool: (name) => this.tool(name, path),
+      call: (name, args) => this.call(name, args, path),
+      read: (name) => this.read(name, path),
+      diffSince: (before) => this.diffSince(before, path),
+      subscribe: (listener) => this.subscribe(listener),
+    };
+  }
+
+  tool(name: string, view: string[] = []): ToolEntry | null {
+    const viewKey = view.join(".");
+    const stack = this.#tools.get(name);
+    if (stack?.length && AgenticSurface.#within(viewKey, name)) return stack[stack.length - 1];
+    for (const source of this.#sources) {
+      const found = source.tools?.(view).find((candidate) => candidate.name === name);
+      if (found) return found;
+    }
+    return null;
+  }
+
+  async call(name: string, args: Record<string, unknown> = {}, view: string[] = []): Promise<unknown> {
+    const entry = this.tool(name, view);
+    if (!entry) throw new Error(`Unknown tool: ${name}`);
+    const verdict = entry.guard?.(args) ?? true;
+    if (verdict !== true) throw new Error(verdict);
+    return await entry.run(args);
+  }
+
+  read(name: string, view: string[] = []): unknown {
+    const entry = this.#resource(name, view);
+    if (!entry) throw new Error(`Unknown resource: ${name}`);
+    return entry.read();
+  }
+
+  /**
+   * The resources that changed since `before`, for reporting a tool call's effect back to the model.
+   *
+   * Runs against the live entries rather than a second snapshot because `report: false` lives on the entry, and a
+   * snapshot deliberately does not publish it.
+   */
+  diffSince(before: SurfaceSnapshot, view: string[] = []): ResourceDiff[] {
+    const prev = new Map(before.resources.map((resource) => [resource.name, resource]));
+    const diffs: ResourceDiff[] = [];
+    const seen = new Set<string>();
+    for (const [name, entry] of this.#activeResources(view)) {
+      seen.add(name);
+      if (entry.report === false) continue;
+      const current = AgenticSurface.#publishResource(name, entry);
+      const last = prev.get(name);
+      if (
+        last &&
+        AgenticSurface.#print(last.value) === AgenticSurface.#print(current.value) &&
+        last.error === current.error
+      )
+        continue;
+      diffs.push({
+        name,
+        ...(current.value !== undefined ? { value: current.value } : {}),
+        ...(current.error !== undefined ? { error: current.error } : {}),
+      });
+    }
+    for (const name of prev.keys()) if (!seen.has(name)) diffs.push({ name, removed: true });
+    return diffs;
+  }
+
+  *#activeTools(view: string[] = []): Generator<[string, ToolEntry]> {
+    const viewKey = view.join(".");
+    const seen = new Set<string>();
+    for (const [name, stack] of this.#tools) {
+      if (!AgenticSurface.#within(viewKey, name)) continue;
+      seen.add(name);
+      yield [name, stack[stack.length - 1]];
+    }
+    for (const source of this.#sources) {
+      for (const entry of source.tools?.(view) ?? []) {
+        if (seen.has(entry.name)) continue;
+        seen.add(entry.name);
+        yield [entry.name, entry];
+      }
+    }
+  }
+
+  *#activeResources(view: string[] = []): Generator<[string, ResourceEntry]> {
+    const viewKey = view.join(".");
+    const seen = new Set<string>();
+    for (const [name, stack] of this.#resources) {
+      if (!AgenticSurface.#within(viewKey, name)) continue;
+      seen.add(name);
+      yield [name, stack[stack.length - 1]];
+    }
+    for (const source of this.#sources) {
+      for (const entry of source.resources?.(view) ?? []) {
+        if (seen.has(entry.name)) continue;
+        seen.add(entry.name);
+        yield [entry.name, entry];
+      }
+    }
+  }
+
+  #resource(name: string, view: string[] = []): ResourceEntry | null {
+    const viewKey = view.join(".");
+    const stack = this.#resources.get(name);
+    if (stack?.length && AgenticSurface.#within(viewKey, name)) return stack[stack.length - 1];
+    for (const source of this.#sources) {
+      const found = source.resources?.(view).find((candidate) => candidate.name === name);
+      if (found) return found;
+    }
+    return null;
+  }
+
+  /** Empty view sees everything; a zone view sees the entries whose scope-prefixed key sits in its subtree. */
+  static #within(viewKey: string, key: string) {
+    return !viewKey || key === viewKey || key.startsWith(`${viewKey}.`);
+  }
+
+  /** The layout cascade: a guide applies to a view when one contains the other — ancestors and descendants, never siblings. */
+  static #guideApplies(viewKey: string, scopeKey: string) {
+    if (!viewKey || !scopeKey || viewKey === scopeKey) return true;
+    return viewKey.startsWith(`${scopeKey}.`) || scopeKey.startsWith(`${viewKey}.`);
+  }
+
+  #stack<E>(map: Map<string, E[]>, key: string, entry: E) {
+    const stack = map.get(key) ?? [];
+    if (stack.length && !this.#warned.has(key)) {
+      this.#warned.add(key);
+      console.warn(`[use-agentic] "${key}" is registered more than once; the newest registration wins.`);
+    }
+    stack.push(entry);
+    map.set(key, stack);
+    this.#notify();
+    return () => {
+      const idx = stack.indexOf(entry);
+      if (idx >= 0) stack.splice(idx, 1);
+      if (!stack.length) map.delete(key);
+      this.#notify();
+    };
+  }
+
+  #notify() {
+    for (const listener of this.#listeners) listener();
+  }
+
+  static #publishTool(name: string, entry: ToolEntry): PublishedTool {
+    return {
+      name,
+      ...(entry.description ? { description: entry.description } : {}),
+      ...(entry.parameters ? { parameters: entry.parameters } : {}),
+      ...(entry.effect ? { effect: entry.effect } : {}),
+      needsConfirm: entry.confirm !== undefined && entry.confirm !== false,
+    };
+  }
+
+  static #publishResource(name: string, entry: ResourceEntry): PublishedResource {
+    const base = { name, ...(entry.description ? { description: entry.description } : {}) };
+    try {
+      return { ...base, value: entry.read() };
+    } catch (error) {
+      return { ...base, error: error instanceof Error ? error.message : String(error) };
+    }
+  }
+
+  /** Serialized equality, because a read may rebuild an equal object on every call. */
+  static #print(value: unknown) {
+    try {
+      return JSON.stringify(value) ?? "undefined";
+    } catch {
+      return "[unserializable]";
+    }
+  }
+}

package/vendor/use-agentic/WIRE.md

@@ -0,0 +1,57 @@
+# The turn wire
+
+`httpRunner` speaks this contract. Any backend that answers it can drive an `AgentSession` — the session, the
+tools, and the loop stay in the client; the server serves exactly one stateless model turn per request.
+
+## Request
+
+`POST <url>` with `content-type: application/json`:
+
+```jsonc
+{
+  "messages": [
+    { "role": "user", "text": "Trim the intro scene" },
+    { "role": "assistant", "text": "", "toolCalls": [{ "id": "c1", "name": "setSceneSeconds", "args": { "seconds": 4 } }] },
+    { "role": "tool", "toolResults": [{ "id": "c1", "name": "setSceneSeconds", "changes": [{ "name": "totalSeconds", "value": 39 }] }] }
+  ],
+  "tools": [
+    {
+      "name": "setSceneSeconds",
+      "description": "Change this scene's length in seconds",
+      "parameters": { "type": "object", "properties": { "seconds": { "type": "number" } }, "required": ["seconds"], "additionalProperties": false },
+      "effect": "mutation",
+      "needsConfirm": false
+    }
+  ],
+  "context": [{ "kind": "screen", "scopes": [{ "path": "scene-s1", "label": "Intro", "kind": "scene" }] }],
+  "instructions": "You are editing a video project."   // optional
+}
+```
+
+- `messages` is the whole transcript in `ChatMessage` shape (`types.ts`). The server maps it to its provider's
+  format and maps the answer back; it never executes a tool — `tools` is a schema catalogue, not an offer.
+- `context` blocks are host vocabulary. The server forwards them to the model as data, framed as data.
+- Everything is JSON-serializable by contract; a tool whose `result` is not is the tool's bug.
+
+## Response
+
+`200` with a single JSON object:
+
+```jsonc
+{
+  "text": "Trimmed. Anything else?",                                  // optional
+  "toolCalls": [{ "id": "c2", "name": "renderProject", "args": {} }], // optional
+  "stop": "end"                                                       // "end" | "toolUse"; defaults from toolCalls
+}
+```
+
+Any non-2xx status is surfaced to the session as one error event and ends the turn; a string `message` or
+`error` field in a JSON body is quoted in that event, and any other body is not interpreted.
+
+## Streaming
+
+The same endpoint may answer `text/event-stream` instead when the request's `accept` names it: one `RunnerEvent`
+(`types.ts`) JSON object per SSE `data:` line, ending with the `done` event. A failure after the stream opened
+travels as one `error` event — the status line is already gone by then. `httpRunner` sends
+`accept: text/event-stream, application/json` and branches on the response's content type, so a server that never
+streams keeps answering the single JSON object above unchanged.

package/vendor/use-agentic/httpRunner.ts

@@ -0,0 +1,115 @@
+import type { AgentRunner, RunnerEvent, ToolCallRequest } from "./types";
+
+export interface HttpRunnerOptions {
+  url: string;
+  headers?: () => Record<string, string>;
+  /** Swap the transport — tests, a framework's own HTTP client, a custom fetch with credentials. */
+  fetcher?: typeof fetch;
+}
+
+interface TurnAnswer {
+  text?: string;
+  toolCalls?: ToolCallRequest[];
+  stop?: "end" | "toolUse";
+}
+
+const eventTypes = new Set(["text", "toolCall", "done", "error"]);
+
+const parseFrame = (frame: string): RunnerEvent | null => {
+  const data = frame
+    .split("\n")
+    .filter((line) => line.startsWith("data:"))
+    .map((line) => line.slice(5).trim())
+    .join("\n");
+  if (!data) return null;
+  const event = JSON.parse(data) as RunnerEvent;
+  return eventTypes.has((event as { type?: string }).type ?? "") ? event : null;
+};
+
+/**
+ * A manual reader loop rather than for-await: ReadableStream async iteration is still missing from browsers the
+ * chat runs in. Breaking out early cancels the stream so the connection is released.
+ */
+async function* streamedEvents(body: ReadableStream<Uint8Array>, signal: AbortSignal): AsyncGenerator<RunnerEvent> {
+  const reader = body.getReader();
+  const decoder = new TextDecoder();
+  let buffer = "";
+  let ended = false;
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      let cut = buffer.indexOf("\n\n");
+      while (cut !== -1) {
+        const frame = buffer.slice(0, cut);
+        buffer = buffer.slice(cut + 2);
+        cut = buffer.indexOf("\n\n");
+        const event = parseFrame(frame);
+        if (!event) continue;
+        yield event;
+        if (event.type === "done" || event.type === "error") {
+          ended = true;
+          return;
+        }
+      }
+    }
+  } catch (error) {
+    ended = true;
+    if (!signal.aborted) yield { type: "error", message: error instanceof Error ? error.message : String(error) };
+    return;
+  } finally {
+    void reader.cancel().catch(() => undefined);
+  }
+  if (!ended) yield { type: "error", message: "The turn stream ended without a done event." };
+}
+
+const turnErrorMessage = async (response: Response): Promise<string> => {
+  const fallback = `Agent turn failed: ${response.status}`;
+  try {
+    const body = (await response.json()) as { message?: unknown; error?: unknown };
+    const message = typeof body.message === "string" ? body.message : typeof body.error === "string" ? body.error : "";
+    return message ? `Agent turn failed: ${message}` : fallback;
+  } catch {
+    return fallback;
+  }
+};
+
+/**
+ * The default runner: one stateless POST per assistant turn, negotiated via `accept`. A server that streams
+ * answers `text/event-stream` — one `RunnerEvent` JSON per SSE `data:` line, ending with `done` — and one that
+ * does not answers the single JSON `TurnAnswer`; both ride the same endpoint and the same request JSON.
+ *
+ * The wire is documented in WIRE.md so any backend can serve it.
+ */
+export const httpRunner = ({ url, headers, fetcher }: HttpRunnerOptions): AgentRunner => ({
+  async *run(request) {
+    const response = await (fetcher ?? fetch)(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        accept: "text/event-stream, application/json",
+        ...(headers?.() ?? {}),
+      },
+      body: JSON.stringify({
+        messages: request.messages,
+        tools: request.tools,
+        context: request.context,
+        ...(request.instructions ? { instructions: request.instructions } : {}),
+      }),
+      signal: request.signal,
+    });
+    if (!response.ok) {
+      yield { type: "error", message: await turnErrorMessage(response) };
+      return;
+    }
+    if (response.headers.get("content-type")?.includes("text/event-stream") && response.body) {
+      yield* streamedEvents(response.body, request.signal);
+      return;
+    }
+    const turn = (await response.json()) as TurnAnswer;
+    if (turn.text) yield { type: "text", delta: turn.text };
+    for (const call of turn.toolCalls ?? []) yield { type: "toolCall", id: call.id, name: call.name, args: call.args };
+    yield { type: "done", stop: turn.stop ?? (turn.toolCalls?.length ? "toolUse" : "end") };
+  },
+});

package/vendor/use-agentic/index.ts

@@ -0,0 +1,14 @@
+"use client";
+export * from "./Agentic";
+export * from "./AgenticSurface";
+export * from "./AgentProvider";
+export * from "./AgentScope";
+export * from "./AgentSession";
+export * from "./httpRunner";
+export * from "./surfaceContext";
+export * from "./types";
+export * from "./useAgent";
+export * from "./useAgentGuide";
+export * from "./useAgentResource";
+export * from "./useAgentState";
+export * from "./useAgentTool";

package/vendor/use-agentic/surfaceContext.ts

@@ -0,0 +1,9 @@
+"use client";
+import { createContext, useContext } from "react";
+import { AgenticSurface } from "./AgenticSurface";
+
+export const SurfaceContext = createContext<AgenticSurface | null>(null);
+export const ScopeContext = createContext<string[]>([]);
+
+export const useSurface = () => useContext(SurfaceContext) ?? AgenticSurface.shared;
+export const useScopePath = () => useContext(ScopeContext);

package/vendor/use-agentic/types.ts

@@ -0,0 +1,144 @@
+export type JsonSchema = Record<string, unknown>;
+
+export type ToolEffect = "state" | "query" | "mutation";
+
+/** `true` asks with a default message, a string is the message, a function decides from the arguments. */
+export type ToolConfirm = boolean | string | ((args: Record<string, unknown>) => string | boolean);
+
+/** Re-checked at the moment of execution; a string is the refusal reason the agent reads. */
+export type ToolGuard = (args: Record<string, unknown>) => true | string;
+
+export interface ToolEntry {
+  name: string;
+  description?: string;
+  parameters?: JsonSchema;
+  effect?: ToolEffect;
+  confirm?: ToolConfirm;
+  guard?: ToolGuard;
+  run: (args: Record<string, unknown>) => unknown;
+}
+
+export interface ResourceEntry {
+  name: string;
+  description?: string;
+  /** `false` keeps it out of post-call diff reports — for values that change on their own every second. */
+  report?: boolean;
+  read: () => unknown;
+}
+
+export interface ScopeEntry {
+  id: string;
+  label?: string;
+  kind?: string;
+}
+
+/**
+ * A bulk contributor of entries whose names are already full — how a host store joins the surface. `view` is the
+ * scope path a zone session reads through; a source that ignores it contributes the same entries to every view.
+ */
+export interface SurfaceSource {
+  tools?: (view?: string[]) => ToolEntry[];
+  resources?: (view?: string[]) => ResourceEntry[];
+  subscribe?: (listener: () => void) => () => void;
+}
+
+/**
+ * The reading half of a surface — what a session consumes. `AgenticSurface` is one; `surface.view(path)` answers a
+ * zone-scoped one over the same registry, so zones are views of the screen, never walls between its parts.
+ */
+export interface SurfaceView {
+  snapshot(): SurfaceSnapshot;
+  tool(name: string): ToolEntry | null;
+  call(name: string, args?: Record<string, unknown>): Promise<unknown>;
+  read(name: string): unknown;
+  diffSince(before: SurfaceSnapshot): ResourceDiff[];
+  subscribe(listener: () => void): () => void;
+}
+
+export interface PublishedTool {
+  name: string;
+  description?: string;
+  parameters?: JsonSchema;
+  effect?: ToolEffect;
+  needsConfirm: boolean;
+}
+
+export interface PublishedResource {
+  name: string;
+  description?: string;
+  value?: unknown;
+  error?: string;
+}
+
+export interface PublishedScope {
+  path: string;
+  label?: string;
+  kind?: string;
+}
+
+export interface SurfaceSnapshot {
+  tools: PublishedTool[];
+  resources: PublishedResource[];
+  scopes: PublishedScope[];
+  /** Standing guidance texts, in registration order. Folded into the turn's instructions, not into context. */
+  guides: string[];
+}
+
+export interface ResourceDiff {
+  name: string;
+  value?: unknown;
+  error?: string;
+  removed?: boolean;
+}
+
+export type ChatRole = "user" | "assistant" | "tool";
+
+export interface ToolCallRequest {
+  id: string;
+  name: string;
+  args: Record<string, unknown>;
+}
+
+export interface ToolCallResult {
+  id: string;
+  name: string;
+  /** What `run` returned. Must be JSON-serializable — it rides the wire back to the model. */
+  result?: unknown;
+  /** What the call changed on the surface — the whole report for a tool that returns nothing. */
+  changes?: ResourceDiff[];
+  error?: string;
+}
+
+export interface ChatMessage {
+  role: ChatRole;
+  text?: string;
+  toolCalls?: ToolCallRequest[];
+  toolResults?: ToolCallResult[];
+  /** A failed or capped turn, recorded in the transcript rather than thrown past it. */
+  error?: string;
+}
+
+/** One block of screen context the host assembles per turn. `kind` is the host's vocabulary; the wire forwards it verbatim. */
+export interface ContextBlock {
+  kind: string;
+  [key: string]: unknown;
+}
+
+export type RunnerEvent =
+  | { type: "text"; delta: string }
+  | { type: "toolCall"; id: string; name: string; args: Record<string, unknown> }
+  | { type: "done"; stop: "end" | "toolUse" }
+  | { type: "error"; message: string };
+
+export interface RunnerRequest {
+  messages: ChatMessage[];
+  tools: PublishedTool[];
+  context: ContextBlock[];
+  instructions?: string;
+  signal: AbortSignal;
+}
+
+/** One model turn: request in, streamed events out. Where the loop runs is the implementation's business. */
+export interface AgentRunner {
+  run: (request: RunnerRequest) => AsyncIterable<RunnerEvent>;
+}

package/vendor/use-agentic/useAgent.ts

@@ -0,0 +1,17 @@
+"use client";
+import { createContext, useContext, useSyncExternalStore } from "react";
+import type { AgentSession } from "./AgentSession";
+
+export const SessionContext = createContext<AgentSession | null>(null);
+
+/** The enclosing session, re-rendering on every session change. `send`/`abort` are safe to destructure. */
+export const useAgent = (): AgentSession => {
+  const session = useContext(SessionContext);
+  if (!session) throw new Error("useAgent needs an AgentProvider with a session or a runner.");
+  useSyncExternalStore(
+    session.subscribe,
+    () => session.version,
+    () => session.version,
+  );
+  return session;
+};

package/vendor/use-agentic/useAgentGuide.ts

@@ -0,0 +1,16 @@
+"use client";
+import { useEffect, useRef } from "react";
+import { useScopePath, useSurface } from "./surfaceContext";
+
+/**
+ * Registers standing guidance for the agent while the component is mounted. Guidance is folded into the turn's
+ * instructions — it directs the model, unlike context, which is framed as data. The text is captured at mount
+ * like every declaration on the surface; remount to change it.
+ */
+export const useAgentGuide = (text: string): void => {
+  const surface = useSurface();
+  const scope = useScopePath();
+  const captured = useRef(text);
+  const scopeKey = scope.join(".");
+  useEffect(() => surface.registerGuide(scope, captured.current), [surface, scopeKey]);
+};