@stigmer/react 3.2.3 → 3.4.0

package/src/datastore/useUpdateRecord.ts

@@ -0,0 +1,95 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import { create, type JsonObject } from "@bufbuild/protobuf";
+import {
+  UpdateRecordRequestSchema,
+  type RecordEnvelope,
+} from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/record_io_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+import type { RecordScope } from "./useRecordList.js";
+
+/** Arguments for a single record update. */
+export interface UpdateRecordArgs extends RecordScope {
+  /** Record id (`dsr_…`). */
+  readonly id: string;
+  /**
+   * Partial merge (DD-005): only the supplied fields change; an
+   * explicit `null` clears a field; absent fields keep their stored
+   * values. Constraints evaluate on the merged result. Build this from
+   * per-field edits with `buildUpdateFields`.
+   */
+  readonly fields: JsonObject;
+}
+
+/** Return value of {@link useUpdateRecord}. */
+export interface UseUpdateRecordReturn {
+  /**
+   * Update one record by id. Resolves with the merged envelope. Rejects
+   * — and sets `error` — on denial or constraint violation; the error's
+   * message is the server's relayable text, byte-for-byte.
+   */
+  readonly updateRecord: (args: UpdateRecordArgs) => Promise<RecordEnvelope>;
+  /** `true` while the update is in flight. */
+  readonly isUpdating: boolean;
+  /** Error from the last failed update, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that wraps `datastore.updateRecord()` with loading and
+ * error state.
+ *
+ * The RPC is an honest tri-state partial merge — the hook adds no
+ * merge semantics of its own. A record in another partition is
+ * NOT_FOUND (DD-010: partition scoping is structural).
+ *
+ * @example
+ * ```tsx
+ * const { updateRecord } = useUpdateRecord();
+ * await updateRecord({
+ *   org: "acme",
+ *   datastore: "clinic",
+ *   collection: "bookings",
+ *   id: "dsr_01j9...",
+ *   fields: { patient_phone: "+15550100", notes: null }, // notes cleared
+ * });
+ * ```
+ */
+export function useUpdateRecord(): UseUpdateRecordReturn {
+  const stigmer = useStigmer();
+  const [isUpdating, setIsUpdating] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const updateRecord = useCallback(
+    async (args: UpdateRecordArgs): Promise<RecordEnvelope> => {
+      setIsUpdating(true);
+      setError(null);
+      try {
+        return await stigmer.datastore.updateRecord(
+          create(UpdateRecordRequestSchema, {
+            org: args.org,
+            datastore: args.datastore,
+            collection: args.collection,
+            partition: args.partition ?? "",
+            id: args.id,
+            fields: args.fields,
+          }),
+        );
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsUpdating(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { updateRecord, isUpdating, error, clearError };
+}

package/src/environment/EnvironmentListPanel.tsx

@@ -6,6 +6,7 @@ import { getUserMessage } from "@stigmer/sdk";
 import type { Environment } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
 import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import { ResourceVisibilityControl } from "../library/ResourceVisibilityControl.js";
+import { EditResourceYamlDialog } from "../manifest/EditResourceYamlDialog.js";
 import { useEnvironmentList } from "./useEnvironmentList.js";
 import { EnvironmentVariableEditor } from "./EnvironmentVariableEditor.js";
 import { isShareRestrictedEnvironment } from "./shareRestriction.js";
@@ -94,6 +95,7 @@ export function EnvironmentListPanel({
     labels,
   );
   const [expandedId, setExpandedId] = useState<string | null>(null);
+  const [yamlEnvironment, setYamlEnvironment] = useState<Environment | null>(null);
 
   if (onRefetchRef) {
     onRefetchRef(refetch);
@@ -179,9 +181,18 @@ export function EnvironmentListPanel({
             onToggle={() => handleToggle(env)}
             readOnly={readOnly}
             onVisibilityChanged={refetch}
+            onEditYaml={() => setYamlEnvironment(env)}
           />
         );
       })}
+      <EditResourceYamlDialog
+        open={yamlEnvironment !== null}
+        onOpenChange={(open) => {
+          if (!open) setYamlEnvironment(null);
+        }}
+        resource={yamlEnvironment}
+        onApplied={refetch}
+      />
     </div>
   );
 }
@@ -196,12 +207,14 @@ function EnvironmentCard({
   onToggle,
   readOnly,
   onVisibilityChanged,
+  onEditYaml,
 }: {
   environment: Environment;
   isExpanded: boolean;
   onToggle: () => void;
   readOnly: boolean;
   onVisibilityChanged: () => void;
+  onEditYaml: () => void;
 }) {
   const name =
     environment.metadata?.name || environment.metadata?.slug || "Unnamed";
@@ -249,6 +262,17 @@ function EnvironmentCard({
           </div>
         </button>
 
+        {!readOnly && (
+          <button
+            type="button"
+            onClick={onEditYaml}
+            aria-label={`Edit ${name} as YAML`}
+            className="shrink-0 rounded px-1.5 py-0.5 text-xs text-muted-foreground transition-colors hover:bg-accent hover:text-accent-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+          >
+            Edit YAML
+          </button>
+        )}
+
         {showVisibilityControl && (
           <ResourceVisibilityControl
             kind="environment"

package/src/execution/ExecutionProgress.tsx

@@ -1,6 +1,7 @@
 "use client";
 
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { cn } from "@stigmer/theme";
 import { ExecutionPhaseBadge } from "./ExecutionPhaseBadge.js";
 import { TodoList } from "./TodoList.js";
@@ -47,10 +48,19 @@ export function ExecutionProgress({
   if (phase === undefined) return null;
 
   const todos = execution.status?.todos;
-  // Populated by the server only on EXECUTION_FAILED — surface it next to the
-  // badge so this widget explains a failure rather than showing a bare phase
-  // (consistent with the failure reason in the message thread).
-  const error = execution.status?.error;
+  // Populated by the server on EXECUTION_FAILED and EXECUTION_TERMINATED —
+  // surface it next to the badge so this widget explains a failure rather
+  // than showing a bare phase (consistent with the message thread).
+  //
+  // CANCELLED is carved out: cancel is a quiet terminal state, not a failure
+  // (stigmer#282). A CANCELLED execution can still carry a non-empty error —
+  // cancel preserves a preexisting error by design, and an older server may
+  // have written a cancellation sentinel — so the phase, not the error field,
+  // decides whether to render the alert. The muted Cancelled badge suffices.
+  const error =
+    phase === ExecutionPhase.EXECUTION_CANCELLED
+      ? undefined
+      : execution.status?.error;
 
   return (
     <div

package/src/execution/MessageThread.tsx

@@ -941,12 +941,20 @@ export function buildThreadItems(
       key: `phase-${lastPhase}`,
     });
 
-    // The server populates `status.error` only on EXECUTION_FAILED. Surface it
+    // The server populates `status.error` on EXECUTION_FAILED and
+    // EXECUTION_TERMINATED — never on a user-initiated cancel. Surface it
     // beside the badge so a failure that produced no messages still explains
     // itself (the CLI shows this reason; the chat previously showed nothing).
     // Kept as its own item so the badge component stays presentational.
+    //
+    // CANCELLED is carved out: cancel is a quiet terminal state, not a failure
+    // (stigmer#282). A CANCELLED execution can still carry a non-empty error —
+    // cancel preserves a preexisting error by design (merge semantics), and an
+    // older server may have written a "Execution cancelled" sentinel — so the
+    // phase, not the error field, decides whether to render the loud banner.
+    // The muted Cancelled phase badge above remains the visible state.
     const reason = lastExec?.status?.error;
-    if (reason) {
+    if (reason && lastPhase !== ExecutionPhase.EXECUTION_CANCELLED) {
       const specMessage = lastExec?.spec?.message;
       // A failed build turn offers no inline Retry: resending its label as an
       // ordinary message would drop the buildFromPlan flag (no runner

package/src/execution/__tests__/ExecutionProgress.test.tsx

@@ -0,0 +1,67 @@
+import { describe, it, expect, afterEach } from "vitest";
+import { render, screen, cleanup } from "@testing-library/react";
+import { create } from "@bufbuild/protobuf";
+import {
+  AgentExecutionSchema,
+  AgentExecutionStatusSchema,
+  type AgentExecution,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import { ExecutionProgress } from "../ExecutionProgress";
+
+afterEach(() => {
+  cleanup();
+});
+
+function makeExecution(phase: ExecutionPhase, error?: string): AgentExecution {
+  const exec = create(AgentExecutionSchema);
+  const status = create(AgentExecutionStatusSchema);
+  status.phase = phase;
+  if (error !== undefined) {
+    status.error = error;
+  }
+  exec.status = status;
+  return exec;
+}
+
+describe("ExecutionProgress", () => {
+  it("renders nothing without an execution", () => {
+    const { container } = render(<ExecutionProgress execution={null} />);
+    expect(container.innerHTML).toBe("");
+  });
+
+  it("surfaces the server error as an alert for a FAILED execution", () => {
+    render(
+      <ExecutionProgress
+        execution={makeExecution(
+          ExecutionPhase.EXECUTION_FAILED,
+          "Activity task timed out",
+        )}
+      />,
+    );
+
+    expect(screen.getByRole("alert").textContent).toContain(
+      "Activity task timed out",
+    );
+  });
+
+  // Cancelled is a quiet terminal state (stigmer#282): a CANCELLED execution
+  // can legitimately carry a non-empty status.error (preserved prior error, or
+  // a pre-fix server's "Execution cancelled" sentinel), so the phase — not the
+  // error field — decides whether the alert renders.
+  it("renders a CANCELLED execution quietly even when it carries an error", () => {
+    render(
+      <ExecutionProgress
+        execution={makeExecution(
+          ExecutionPhase.EXECUTION_CANCELLED,
+          "Execution cancelled",
+        )}
+      />,
+    );
+
+    expect(screen.getByText(/cancelled/i)).toBeTruthy();
+    expect(screen.queryByRole("alert")).toBeNull();
+    expect(screen.queryByText("Execution cancelled")).toBeNull();
+  });
+});

package/src/execution/__tests__/MessageThread.test.tsx

@@ -604,6 +604,50 @@ describe("MessageThread", () => {
     expect(screen.queryByText(/stale error/i)).toBeNull();
   });
 
+  // Cancelled is a quiet terminal state (stigmer#282): a user-initiated Stop
+  // must never render as a failure. A CANCELLED execution can legitimately
+  // carry a non-empty status.error — cancel preserves a preexisting error by
+  // design, and pre-fix servers wrote an "Execution cancelled" sentinel — so
+  // the phase, not the error field, decides whether the loud banner renders.
+  it("renders a CANCELLED execution quietly even when it carries a legacy error sentinel", () => {
+    const exec = makeExecution({
+      id: "exec-cancelled",
+      specMessage: "do the thing",
+      phase: ExecutionPhase.EXECUTION_CANCELLED,
+      error: "Execution cancelled",
+    });
+    const onRetryExecution = vi.fn();
+
+    render(
+      <MessageThread executions={[exec]} onRetryExecution={onRetryExecution} />,
+    );
+
+    // The muted phase badge is the visible cancelled state.
+    expect(screen.getByText(/cancelled/i)).toBeTruthy();
+
+    // No destructive banner, no error text, no Retry.
+    expect(screen.queryByRole("alert")).toBeNull();
+    expect(screen.queryByText("Execution cancelled")).toBeNull();
+    expect(screen.queryByRole("button", { name: /retry/i })).toBeNull();
+  });
+
+  it("renders a CANCELLED execution with a preserved prior error quietly", () => {
+    const exec = makeExecution({
+      id: "exec-cancelled-preserved",
+      phase: ExecutionPhase.EXECUTION_CANCELLED,
+      error: "Execution interrupted: agent was unresponsive. Retry or resume.",
+    });
+
+    render(<MessageThread executions={[exec]} />);
+
+    expect(screen.getByText(/cancelled/i)).toBeTruthy();
+    // Neither the loud alert framing nor the neutral interrupted/Resume
+    // framing may appear — the preserved error stays out of the transcript.
+    expect(screen.queryByText(/Execution interrupted/i)).toBeNull();
+    expect(screen.queryByRole("alert")).toBeNull();
+    expect(screen.queryByRole("button", { name: /resume/i })).toBeNull();
+  });
+
   it("offers a Retry that resends the originating message on failure", () => {
     const exec = makeExecution({
       id: "exec-retry",

package/src/execution/__tests__/useArtifactInspection.test.tsx

@@ -119,12 +119,20 @@ describe("useArtifactInspection — detection + apply", () => {
 
   it("applies a detected Agent and fires onApplied with the result", async () => {
     const getArtifactContent = vi.fn().mockResolvedValue(contentResult(AGENT_YAML));
+    // The apply path routes through the kind-agnostic manifest engine:
+    // the hook parses the YAML into a ManifestDocument and hands it to
+    // stigmer.manifest.apply.
     const apply = vi.fn().mockResolvedValue({
-      metadata: { name: "my-agent", org: "acme", slug: "my-agent" },
+      yamlKind: "Agent",
+      displayName: "Agent",
+      name: "my-agent",
+      org: "acme",
+      slug: "my-agent",
+      id: "agt_01",
     });
     const stigmer = {
       agentExecution: { getArtifactContent },
-      agent: { apply },
+      manifest: { apply },
     } as unknown as Stigmer;
     const onApplied = vi.fn();
 
@@ -144,6 +152,8 @@ describe("useArtifactInspection — detection + apply", () => {
 
     expect(apply).toHaveBeenCalledTimes(1);
     expect(apply.mock.calls[0][0].name).toBe("my-agent");
+    expect(apply.mock.calls[0][0].handler.yamlKind).toBe("Agent");
+    expect(apply.mock.calls[0][0].org).toBe("acme");
     await waitFor(() => expect(result.current.applyResult?.kind).toBe("Agent"));
     expect(onApplied).toHaveBeenCalledTimes(1);
     expect(onApplied.mock.calls[0][0].name).toBe("my-agent");

package/src/execution/__tests__/useCreateAgentExecution.test.tsx

@@ -137,6 +137,92 @@ describe("useCreateAgentExecution — one-call session bootstrap (sessionSpec)",
     expect(input.sessionSpec.executionTarget).toBeUndefined();
   });
 
+  it("passes the metadata map through on the bootstrap spec", async () => {
+    const { result } = renderHook(() => useCreateAgentExecution(), {
+      wrapper: createWrapper(makeMockClient()),
+    });
+
+    await act(async () => {
+      await result.current.create({
+        org: "acme",
+        message: "Hello",
+        sessionSpec: {
+          agentInstanceId: "ain-1",
+          metadata: { "acme/tenant": "t-1" },
+        },
+      });
+    });
+
+    const input = mockCreate.mock.calls[0][0];
+    expect(input.sessionSpec.metadata).toEqual({ "acme/tenant": "t-1" });
+  });
+
+  it("maps the typed sessionContext onto the reserved metadata key", async () => {
+    const { result } = renderHook(() => useCreateAgentExecution(), {
+      wrapper: createWrapper(makeMockClient()),
+    });
+
+    await act(async () => {
+      await result.current.create({
+        org: "acme",
+        message: "Hello",
+        sessionSpec: {
+          agentInstanceId: "ain-1",
+          sessionContext: "Role: platform admin",
+        },
+      });
+    });
+
+    const input = mockCreate.mock.calls[0][0];
+    expect(input.sessionSpec.metadata).toEqual({
+      "stigmer.ai/session-context": "Role: platform admin",
+    });
+  });
+
+  it("lets the typed sessionContext win over a raw entry under the reserved key", async () => {
+    const { result } = renderHook(() => useCreateAgentExecution(), {
+      wrapper: createWrapper(makeMockClient()),
+    });
+
+    await act(async () => {
+      await result.current.create({
+        org: "acme",
+        message: "Hello",
+        sessionSpec: {
+          agentInstanceId: "ain-1",
+          metadata: {
+            "acme/tenant": "t-1",
+            "stigmer.ai/session-context": "stale raw value",
+          },
+          sessionContext: "typed value",
+        },
+      });
+    });
+
+    const input = mockCreate.mock.calls[0][0];
+    expect(input.sessionSpec.metadata).toEqual({
+      "acme/tenant": "t-1",
+      "stigmer.ai/session-context": "typed value",
+    });
+  });
+
+  it("omits metadata entirely when neither field is provided", async () => {
+    const { result } = renderHook(() => useCreateAgentExecution(), {
+      wrapper: createWrapper(makeMockClient()),
+    });
+
+    await act(async () => {
+      await result.current.create({
+        org: "acme",
+        message: "Hello",
+        sessionSpec: { agentInstanceId: "ain-1" },
+      });
+    });
+
+    const input = mockCreate.mock.calls[0][0];
+    expect(input.sessionSpec.metadata).toBeUndefined();
+  });
+
   it("returns the server-assigned session id from the bootstrap response", async () => {
     mockCreate.mockResolvedValueOnce({
       metadata: { id: "aex-1" },

package/src/execution/useCreateAgentExecution.ts

@@ -2,12 +2,13 @@
 
 import { useCallback, useState } from "react";
 import type { JsonObject } from "@bufbuild/protobuf";
-import type {
-  AttachmentInput,
-  EnvVarInput,
-  McpServerUsageInput,
-  ResourceRef,
-  WorkspaceEntryInput,
+import {
+  mergeSessionContext,
+  type AttachmentInput,
+  type EnvVarInput,
+  type McpServerUsageInput,
+  type ResourceRef,
+  type WorkspaceEntryInput,
 } from "@stigmer/sdk";
 import { useStigmer } from "../hooks.js";
 import { toError } from "../internal/toError.js";
@@ -41,6 +42,36 @@ export interface BootstrapSessionSpec {
   readonly mcpServerUsages?: McpServerUsageInput[];
   /** Skill references to enable for executions in this session. */
   readonly skillRefs?: ResourceRef[];
+  /**
+   * Custom key-value pairs stored on the created session's
+   * `SessionSpec.metadata`.
+   *
+   * A passthrough for embedder-owned keys (correlation IDs, tenant tags)
+   * and for platform-reserved `stigmer.ai/*` keys set explicitly. For the
+   * common case — standing user context injected into the agent's prompt —
+   * prefer the typed {@link sessionContext} field, which maps onto the
+   * reserved `stigmer.ai/session-context` key and wins over a raw entry
+   * under that key when both are provided.
+   */
+  readonly metadata?: Record<string, string>;
+  /**
+   * Standing, per-user context the agent receives on every turn but the
+   * conversation UI never renders — who the caller is, their experience
+   * level, their standing instructions (stigmer/stigmer#286).
+   *
+   * Stored on the created session's `SessionSpec.metadata` under
+   * `stigmer.ai/session-context`; the agent runner injects it into the
+   * system prompt as already-known background, so agents can greet the
+   * user by name and calibrate depth/defaults from the first turn without
+   * a visible context preamble.
+   *
+   * Personalization, not authorization: anyone who can create the session
+   * can set this (the same trust level as authoring the first message).
+   * Hidden from the conversation thread, not from the API — `session.get`
+   * returns it, so never put secrets here; secrets belong in `runtimeEnv`
+   * or Environment resources. Large values bloat every prompt.
+   */
+  readonly sessionContext?: string;
   /** Execution harness. Immutable after the first execution runs. */
   readonly harness?: HarnessOption;
   /** Where session activities execute. Immutable after the first execution runs. */
@@ -293,6 +324,10 @@ export function useCreateAgentExecution(): UseCreateAgentExecutionReturn {
               workspaceEntries: input.sessionSpec.workspaceEntries,
               mcpServerUsages: input.sessionSpec.mcpServerUsages,
               skillRefs: input.sessionSpec.skillRefs,
+              metadata: mergeSessionContext(
+                input.sessionSpec.metadata,
+                input.sessionSpec.sessionContext,
+              ),
               harness: input.sessionSpec.harness
                 ? toProtoHarness(input.sessionSpec.harness)
                 : undefined,