@superxd-studio/adptr 0.5.0

package/source/reusable/interactions/agent.ts

@@ -0,0 +1,259 @@
+import { z } from "zod";
+import {
+  InteractionStore,
+  identity,
+  shortText,
+  bodyText,
+  jsonSchema,
+  newIdentity,
+  type JsonValue,
+} from "./store.js";
+export const agentStepSchema = z.strictObject({
+  id: identity,
+  title: shortText,
+  tool: shortText,
+  input: jsonSchema,
+  scope: shortText,
+});
+export type AgentStep = z.infer<typeof agentStepSchema>;
+export interface AgentRequest {
+  requestId: string;
+  step: AgentStep;
+  approvedUntil: number;
+}
+const resultSchema = z.discriminatedUnion("status", [
+  z.strictObject({ requestId: identity, status: z.literal("completed"), output: bodyText }),
+  z.strictObject({ requestId: identity, status: z.literal("rejected"), reason: shortText }),
+  z.strictObject({ requestId: identity, status: z.literal("unknown") }),
+]);
+export type AgentResult = z.infer<typeof resultSchema>;
+export type AgentReceipt = AgentResult | { requestId: string; status: "pending" | "not-found" };
+const receiptSchema = z.union([
+  resultSchema,
+  z.strictObject({ requestId: identity, status: z.enum(["pending", "not-found"]) }),
+]);
+export interface AgentAdapter {
+  /** Authorise on the server and deduplicate by requestId. Approval is only for this frozen step. */
+  execute(
+    request: AgentRequest,
+    signal: AbortSignal,
+    progress: (message: string) => void,
+  ): Promise<AgentResult>;
+  /** Look up the same receipt. not-found must mean definitely not accepted, not eventually invisible. */
+  lookup(requestId: string, signal: AbortSignal): Promise<AgentReceipt>;
+}
+export interface AgentSnapshot {
+  steps: readonly AgentStep[];
+  completed: readonly { stepId: string; requestId: string; output: string }[];
+  phase:
+    | "ready"
+    | "approval"
+    | "running"
+    | "checking"
+    | "failed"
+    | "uncertain"
+    | "denied"
+    | "expired"
+    | "complete";
+  request?: AgentRequest;
+  progress?: string;
+  reason?: string;
+}
+type AgentEvent =
+  | { type: "propose"; request: AgentRequest }
+  | { type: "approve" }
+  | { type: "check" }
+  | { type: "progress"; message: string }
+  | { type: "settle"; result: AgentResult }
+  | { type: "uncertain" }
+  | { type: "deny" }
+  | { type: "expire" }
+  | { type: "revise"; steps: readonly AgentStep[] };
+export function agentReducer(state: AgentSnapshot, event: AgentEvent): AgentSnapshot {
+  switch (event.type) {
+    case "propose":
+      return {
+        ...state,
+        phase: "approval",
+        request: event.request,
+        progress: undefined,
+        reason: undefined,
+      };
+    case "approve":
+      return { ...state, phase: "running", progress: undefined };
+    case "check":
+      return { ...state, phase: "checking" };
+    case "progress":
+      return { ...state, progress: event.message };
+    case "uncertain":
+      return { ...state, phase: "uncertain", progress: undefined };
+    case "deny":
+      return { ...state, phase: "denied", progress: undefined };
+    case "expire":
+      return { ...state, phase: "expired" };
+    case "revise":
+      return { ...state, steps: event.steps };
+    case "settle": {
+      if (event.result.status === "unknown")
+        return { ...state, phase: "uncertain", progress: undefined };
+      if (event.result.status === "rejected")
+        return { ...state, phase: "failed", reason: event.result.reason, progress: undefined };
+      if (!state.request) return state;
+      const completed = [
+        ...state.completed,
+        {
+          stepId: state.request.step.id,
+          requestId: state.request.requestId,
+          output: event.result.output,
+        },
+      ];
+      return {
+        ...state,
+        completed,
+        phase: completed.length === state.steps.length ? "complete" : "ready",
+        request: undefined,
+        progress: undefined,
+        reason: undefined,
+      };
+    }
+  }
+}
+/** Supervises a finite plan. It never schedules work or invents a tool implementation. */
+export class AgentController extends InteractionStore<AgentSnapshot> {
+  private expiry?: ReturnType<typeof setTimeout>;
+  private ttl: number;
+  constructor(
+    private adapter: AgentAdapter,
+    steps: readonly AgentStep[],
+    private options: { id?: () => string; now?: () => number; approvalMs?: number } = {},
+  ) {
+    const parsed = z.array(agentStepSchema).min(1).max(50).parse(steps);
+    if (new Set(parsed.map((s) => s.id)).size !== parsed.length)
+      throw new Error("Duplicate plan step");
+    super({ steps: parsed, completed: [], phase: "ready" });
+    this.ttl = z
+      .number()
+      .finite()
+      .min(1000)
+      .max(300_000)
+      .parse(options.approvalMs ?? 60_000);
+  }
+  private now() {
+    return (this.options.now ?? Date.now)();
+  }
+  private send(event: AgentEvent) {
+    this.publish(agentReducer(this.state, event));
+  }
+  private propose(request: AgentRequest) {
+    clearTimeout(this.expiry);
+    this.send({ type: "propose", request });
+    this.expiry = setTimeout(
+      () => {
+        if (this.state.phase === "approval" && this.state.request?.requestId === request.requestId)
+          this.send({ type: "expire" });
+      },
+      Math.max(0, request.approvedUntil - this.now()),
+    );
+  }
+  revise(steps: readonly AgentStep[]) {
+    if (this.disposed || this.state.phase !== "ready" || this.state.completed.length) return false;
+    const parsed = z.array(agentStepSchema).min(1).max(50).safeParse(steps);
+    if (!parsed.success || new Set(parsed.data.map((s) => s.id)).size !== parsed.data.length)
+      return false;
+    this.send({ type: "revise", steps: parsed.data });
+    return true;
+  }
+  next() {
+    if (this.disposed || this.state.phase !== "ready") return false;
+    const step = this.state.steps.find((s) => !this.state.completed.some((r) => r.stepId === s.id));
+    if (!step) return false;
+    this.propose({
+      requestId: this.requestIdentity(this.options.id ?? newIdentity),
+      step,
+      approvedUntil: this.now() + this.ttl,
+    });
+    return true;
+  }
+  approve() {
+    if (this.disposed || this.state.phase !== "approval" || !this.state.request) return false;
+    if (this.now() >= this.state.request.approvedUntil) {
+      this.send({ type: "expire" });
+      return false;
+    }
+    clearTimeout(this.expiry);
+    const request = this.state.request;
+    const { token, signal } = this.request();
+    this.send({ type: "approve" });
+    void (async () => {
+      try {
+        const raw = await this.adapter.execute(request, signal, (message) => {
+          if (
+            this.current(token) &&
+            this.state.phase === "running" &&
+            this.state.request?.requestId === request.requestId
+          ) {
+            const text = shortText.safeParse(message);
+            if (text.success) this.send({ type: "progress", message: text.data });
+          }
+        });
+        const result = resultSchema.parse(raw);
+        if (result.requestId !== request.requestId) throw new Error("Wrong receipt");
+        if (this.current(token)) this.send({ type: "settle", result });
+      } catch {
+        if (this.current(token)) this.send({ type: "uncertain" });
+      }
+    })();
+    return true;
+  }
+  deny() {
+    if (this.disposed || this.state.phase !== "approval") return false;
+    clearTimeout(this.expiry);
+    this.send({ type: "deny" });
+    return true;
+  }
+  stop() {
+    if (this.disposed || this.state.phase !== "running") return false;
+    ++this.generation;
+    this.abort?.abort();
+    this.send({ type: "uncertain" });
+    return true;
+  }
+  renew() {
+    if (this.disposed || !["failed", "expired"].includes(this.state.phase) || !this.state.request)
+      return false;
+    this.propose({
+      ...this.state.request,
+      requestId:
+        this.state.phase === "failed"
+          ? this.requestIdentity(this.options.id ?? newIdentity)
+          : this.state.request.requestId,
+      approvedUntil: this.now() + this.ttl,
+    });
+    return true;
+  }
+  check() {
+    if (this.disposed || this.state.phase !== "uncertain" || !this.state.request) return false;
+    const request = this.state.request;
+    const { token, signal } = this.request();
+    this.send({ type: "check" });
+    void (async () => {
+      try {
+        const receipt = receiptSchema.parse(await this.adapter.lookup(request.requestId, signal));
+        if (receipt.requestId !== request.requestId) throw new Error("Wrong receipt");
+        if (!this.current(token)) return;
+        if (receipt.status === "not-found")
+          this.propose({ ...request, approvedUntil: this.now() + this.ttl });
+        else if (receipt.status === "pending") this.send({ type: "uncertain" });
+        else this.send({ type: "settle", result: resultSchema.parse(receipt) });
+      } catch {
+        if (this.current(token)) this.send({ type: "uncertain" });
+      }
+    })();
+    return true;
+  }
+  override dispose() {
+    clearTimeout(this.expiry);
+    super.dispose();
+  }
+}
+export type { JsonValue };

package/source/reusable/interactions/artifact.ts

@@ -0,0 +1,236 @@
+import { z } from "zod";
+import { InteractionStore, identity, shortText, bodyText, newIdentity } from "./store.js";
+export const artifactSchema = z
+  .strictObject({
+    id: identity,
+    title: shortText,
+    revision: identity,
+    content: bodyText,
+    canEdit: z.boolean(),
+    history: z.array(z.strictObject({ revision: identity, content: bodyText })).max(100),
+  })
+  .refine(
+    (item) => new Set(item.history.map((v) => v.revision)).size === item.history.length,
+    "Duplicate revision",
+  );
+export type ArtifactRecord = z.infer<typeof artifactSchema>;
+export interface ArtifactRequest {
+  requestId: string;
+  artifactId: string;
+  baseRevision: string;
+  content: string;
+}
+const saveSchema = z.discriminatedUnion("status", [
+  z.strictObject({ requestId: identity, status: z.literal("saved"), record: artifactSchema }),
+  z.strictObject({ requestId: identity, status: z.literal("conflict"), record: artifactSchema }),
+  z.strictObject({ requestId: identity, status: z.literal("rejected"), reason: shortText }),
+  z.strictObject({ requestId: identity, status: z.literal("unknown") }),
+]);
+export type ArtifactResult = z.infer<typeof saveSchema>;
+export type ArtifactReceipt =
+  ArtifactResult | { requestId: string; status: "pending" | "not-found" };
+const receiptSchema = z.union([
+  saveSchema,
+  z.strictObject({ requestId: identity, status: z.enum(["pending", "not-found"]) }),
+]);
+export interface ArtifactAdapter {
+  load(id: string, signal: AbortSignal): Promise<ArtifactRecord>;
+  /** Use compare-and-swap on baseRevision, server permissions and a durable idempotent receipt. */
+  save(request: ArtifactRequest, signal: AbortSignal): Promise<ArtifactResult>;
+  lookup(requestId: string, signal: AbortSignal): Promise<ArtifactReceipt>;
+}
+export interface ArtifactSnapshot {
+  phase:
+    | "idle"
+    | "loading"
+    | "load-error"
+    | "viewing"
+    | "editing"
+    | "saving"
+    | "conflict"
+    | "unknown"
+    | "checking";
+  record?: ArtifactRecord;
+  draft: string;
+  latest?: ArtifactRecord;
+  request?: ArtifactRequest;
+  reason?: string;
+  loadId?: string;
+}
+type ArtifactEvent =
+  | { type: "load"; id: string }
+  | { type: "loaded"; record: ArtifactRecord }
+  | { type: "load-error" }
+  | { type: "edit"; content: string }
+  | { type: "save"; request: ArtifactRequest }
+  | { type: "settle"; result: ArtifactResult }
+  | { type: "unknown" }
+  | { type: "check" }
+  | { type: "not-found" }
+  | { type: "adopt"; keepDraft: boolean };
+export function artifactReducer(state: ArtifactSnapshot, event: ArtifactEvent): ArtifactSnapshot {
+  switch (event.type) {
+    case "load":
+      return { ...state, phase: "loading", loadId: event.id, reason: undefined };
+    case "loaded":
+      return { phase: "viewing", record: event.record, draft: event.record.content };
+    case "load-error":
+      return { ...state, phase: "load-error" };
+    case "edit":
+      return {
+        ...state,
+        phase: "editing",
+        draft: event.content,
+        request: undefined,
+        reason: undefined,
+      };
+    case "save":
+      return { ...state, phase: "saving", request: event.request, reason: undefined };
+    case "unknown":
+      return { ...state, phase: "unknown" };
+    case "check":
+      return { ...state, phase: "checking" };
+    case "not-found":
+      return { ...state, phase: "editing" };
+    case "adopt":
+      return state.latest
+        ? {
+            phase: event.keepDraft ? "editing" : "viewing",
+            record: state.latest,
+            draft: event.keepDraft ? state.draft : state.latest.content,
+          }
+        : state;
+    case "settle": {
+      if (event.result.status === "saved")
+        return {
+          phase: "viewing",
+          record: event.result.record,
+          draft: event.result.record.content,
+        };
+      if (event.result.status === "conflict")
+        return { ...state, phase: "conflict", latest: event.result.record };
+      if (event.result.status === "rejected")
+        return { ...state, phase: "editing", reason: event.result.reason, request: undefined };
+      return { ...state, phase: "unknown" };
+    }
+  }
+}
+export class ArtifactController extends InteractionStore<ArtifactSnapshot> {
+  constructor(
+    private adapter: ArtifactAdapter,
+    private id: () => string = newIdentity,
+  ) {
+    super({ phase: "idle", draft: "" });
+  }
+  private send(event: ArtifactEvent) {
+    this.publish(artifactReducer(this.state, event));
+  }
+  open(id: string) {
+    if (
+      this.disposed ||
+      ["saving", "unknown", "checking", "conflict"].includes(this.state.phase) ||
+      (this.state.record && this.state.draft !== this.state.record.content)
+    )
+      return false;
+    const parsed = identity.safeParse(id);
+    if (!parsed.success) return false;
+    const { token, signal } = this.request();
+    this.send({ type: "load", id: parsed.data });
+    void (async () => {
+      try {
+        const record = artifactSchema.parse(await this.adapter.load(parsed.data, signal));
+        if (record.id !== parsed.data) throw new Error("Wrong artifact");
+        if (this.current(token)) this.send({ type: "loaded", record });
+      } catch {
+        if (this.current(token)) this.send({ type: "load-error" });
+      }
+    })();
+    return true;
+  }
+  edit(content: string) {
+    if (
+      this.disposed ||
+      !this.state.record?.canEdit ||
+      !["viewing", "editing"].includes(this.state.phase) ||
+      !bodyText.safeParse(content).success
+    )
+      return false;
+    this.send({ type: "edit", content });
+    return true;
+  }
+  discard() {
+    if (
+      this.disposed ||
+      !this.state.record ||
+      !["viewing", "editing", "load-error"].includes(this.state.phase)
+    )
+      return false;
+    this.send({ type: "loaded", record: this.state.record });
+    return true;
+  }
+  save() {
+    const state = this.state;
+    if (
+      this.disposed ||
+      state.phase !== "editing" ||
+      !state.record?.canEdit ||
+      state.draft === state.record.content
+    )
+      return false;
+    const request =
+      state.request ??
+      Object.freeze({
+        requestId: this.requestIdentity(this.id),
+        artifactId: state.record.id,
+        baseRevision: state.record.revision,
+        content: state.draft,
+      });
+    const { token, signal } = this.request();
+    this.send({ type: "save", request });
+    void (async () => {
+      try {
+        const result = saveSchema.parse(await this.adapter.save(request, signal));
+        this.validateResult(result, request);
+        if (this.current(token)) this.send({ type: "settle", result });
+      } catch {
+        if (this.current(token)) this.send({ type: "unknown" });
+      }
+    })();
+    return true;
+  }
+  private validateResult(result: ArtifactResult, request: ArtifactRequest) {
+    if (
+      result.requestId !== request.requestId ||
+      ("record" in result && result.record.id !== request.artifactId) ||
+      (result.status === "saved" && result.record.revision === request.baseRevision)
+    )
+      throw new Error("Invalid artifact receipt");
+  }
+  adoptLatest(keepDraft: boolean) {
+    if (this.disposed || this.state.phase !== "conflict" || !this.state.latest) return false;
+    this.send({ type: "adopt", keepDraft });
+    return true;
+  }
+  check() {
+    if (this.disposed || this.state.phase !== "unknown" || !this.state.request) return false;
+    const request = this.state.request;
+    const { token, signal } = this.request();
+    this.send({ type: "check" });
+    void (async () => {
+      try {
+        const receipt = receiptSchema.parse(await this.adapter.lookup(request.requestId, signal));
+        if (receipt.requestId !== request.requestId) throw new Error("Wrong receipt");
+        if (!this.current(token)) return;
+        if (receipt.status === "not-found") this.send({ type: "not-found" });
+        else if (receipt.status === "pending") this.send({ type: "unknown" });
+        else {
+          this.validateResult(saveSchema.parse(receipt), request);
+          this.send({ type: "settle", result: saveSchema.parse(receipt) });
+        }
+      } catch {
+        if (this.current(token)) this.send({ type: "unknown" });
+      }
+    })();
+    return true;
+  }
+}

package/source/reusable/interactions/context.tsx

@@ -0,0 +1,38 @@
+import { createContext, useContext, type ReactNode } from "react";
+import { interactionCopy } from "./copy.js";
+type Widen<T> = T extends string
+  ? string
+  : T extends (...args: never[]) => unknown
+    ? T
+    : T extends object
+      ? { [K in keyof T]: Widen<T[K]> }
+      : T;
+export type InteractionCopy = Widen<typeof interactionCopy>;
+export type InteractionCopyOverrides = {
+  [K in keyof InteractionCopy]?: InteractionCopy[K] extends (...args: never[]) => unknown
+    ? InteractionCopy[K]
+    : InteractionCopy[K] extends object
+      ? Partial<InteractionCopy[K]>
+      : InteractionCopy[K];
+};
+const CopyContext = createContext<InteractionCopy>(interactionCopy);
+/** Scope user-facing copy independently from state identities and server contracts. */
+export function InteractionProvider({
+  copy = {},
+  children,
+}: {
+  copy?: InteractionCopyOverrides;
+  children: ReactNode;
+}) {
+  const parent = useContext(CopyContext);
+  const merged = {
+    ...parent,
+    ...copy,
+    toolStates: { ...parent.toolStates, ...copy.toolStates },
+    agentStates: { ...parent.agentStates, ...copy.agentStates },
+    artifactStates: { ...parent.artifactStates, ...copy.artifactStates },
+    connection: { ...parent.connection, ...copy.connection },
+  };
+  return <CopyContext.Provider value={merged}>{children}</CopyContext.Provider>;
+}
+export const useInteractionCopy = () => useContext(CopyContext);

package/source/reusable/interactions/copy.ts

@@ -0,0 +1,117 @@
+export const interactionCopy = {
+  code: "Code",
+  files: "Files",
+  checks: "Checks",
+  passed: "Passed",
+  failed: "Failed",
+  artifactStates: {
+    idle: "Choose an artifact",
+    loading: "Loading artifact",
+    "load-error": "Artifact unavailable",
+    viewing: "Saved version",
+    editing: "Draft edited",
+    saving: "Saving revision",
+    conflict: "Saved version changed",
+    unknown: "Save result unknown",
+    checking: "Checking save",
+  },
+  invalid: "This content could not be displayed. Ask for an updated version.",
+  explanation: "Progress explanation",
+  supplied: "Reported by the host",
+  inputs: "Inputs",
+  output: "Result",
+  tool: "Tool details",
+  sources: "Sources",
+  source: (index: number, title: string) => `Source ${index}: ${title}`,
+  unavailable: "Source unavailable",
+  noSources: "No sources were supplied.",
+  retrieval: "Context used for this response",
+  included: "Included",
+  excluded: "Not included",
+  checkClaim: "Check this claim",
+  blocked: "This action cannot proceed",
+  model: "Model",
+  context: "Context to include",
+  commands: "Commands",
+  quote: "Quoted excerpt",
+  reply: "Use excerpt in reply",
+  connection: {
+    connected: "Connected",
+    reconnecting: "Reconnecting",
+    disconnected: "Disconnected",
+  },
+  disconnected:
+    "The connection does not tell us whether remote work finished. Check the result before repeating an action.",
+  reconnect: "Reconnect",
+  trace: "Run measurements",
+  notReported: "Not reported",
+  agent: "Supervised plan",
+  plan: "Proposed steps",
+  request: "Review next step",
+  scope: "Approval scope",
+  allow: "Approve this step",
+  deny: "Decline",
+  stop: "Stop waiting",
+  check: "Check status",
+  renew: "Review again",
+  unknown: "The result is unknown. Check the original request before running it again.",
+  approvalHint:
+    "Approval applies only to the displayed step and inputs. The host still checks your permissions.",
+  expires: "Approval expires if you wait too long. Review the step again to continue.",
+  denied: "The step was declined. Earlier completed work stays completed.",
+  complete: "All steps are complete.",
+  toolStates: {
+    pending: "Pending",
+    approval: "Awaiting approval",
+    running: "Running",
+    completed: "Complete",
+    rejected: "Not applied",
+    unknown: "Result unknown",
+  },
+  agentStates: {
+    ready: "Ready to review",
+    approval: "Awaiting approval",
+    running: "Working",
+    checking: "Checking result",
+    failed: "Step not applied",
+    uncertain: "Result unknown",
+    denied: "Declined",
+    expired: "Approval expired",
+    complete: "Complete",
+  },
+  artifact: "Artifact",
+  edit: "Edit draft",
+  save: "Save revision",
+  saving: "Saving revision",
+  discard: "Discard edits",
+  revision: "Revision",
+  artifactContent: "Artifact content",
+  latest: "Latest saved version",
+  localDraft: "Your draft",
+  conflict: "The saved version changed. Compare it with your draft before choosing what to keep.",
+  useLatest: "Use latest saved version",
+  keepDraft: "Keep my draft against the latest version",
+  loadError: "Couldn’t load this artifact. Try again; the current work is still here.",
+  retry: "Try again",
+  idleArtifact: "Choose an artifact to open.",
+  feedback: "Response feedback",
+  helpful: "Helpful",
+  unhelpful: "Needs work",
+  comment: "What should change?",
+  sendFeedback: "Save feedback",
+  savedFeedback: "Feedback saved for this response.",
+  failedFeedback: "Feedback is not confirmed. Retry with the same feedback.",
+  threads: "Conversation history",
+  refresh: "Refresh conversations",
+  active: "Active",
+  archived: "Archived",
+  archive: "Archive conversation",
+  restore: "Restore conversation",
+  rename: "Rename conversation",
+  title: "Conversation title",
+  saveTitle: "Save title",
+  chooseThread: "Choose a conversation to see its saved context.",
+  noThreads: "No conversations in this view.",
+  threadError: "Couldn’t complete that request. The current conversation is still here.",
+  loading: "Loading",
+} as const;