@pylonsync/react 0.4.27 → 0.4.28

package/dist/index.d.ts

@@ -144,6 +144,35 @@ export declare function getReactStorage(): PylonStorage;
 export declare function callFn<T = unknown>(name: string, args?: Record<string, unknown>, options?: {
     token?: string;
 }): Promise<T>;
+/**
+ * Ask an `agent()` run to stop.
+ *
+ * Cancel is durable, not a stream teardown: it lands on the run row,
+ * so it reaches a loop running on a different machine, and abandoning
+ * the SSE connection is NOT a cancel (a detached cloud run is supposed
+ * to survive the window closing).
+ *
+ * The call returns as soon as the request is recorded. A live
+ * generation stops at its next turn boundary — between tool calls
+ * within seconds, or after the current model response finishes.
+ * `run.cancelRequested` is true in that window; drive the stop
+ * button's pending state from it and treat `run.status === "cancelled"`
+ * as the confirmation.
+ *
+ * ```ts
+ * const { run } = useAgentRun(runId);
+ * <button
+ *   disabled={run?.cancelRequested === true}
+ *   onClick={() => cancelAgentRun("helper", runId)}
+ * >Stop</button>
+ * ```
+ */
+export declare function cancelAgentRun(agentName: string, runId: string, options?: {
+    token?: string;
+}): Promise<{
+    runId: string;
+    cancelled: boolean;
+}>;
 /** Options for {@link streamFn}. */
 export interface StreamFnOptions {
     token?: string;

package/dist/useAgentRun.d.ts

@@ -9,23 +9,35 @@
  * ```tsx
  * const { run, messages } = useAgentRun(runId);
  * // messages[i]: { role: "user" | "assistant", content: string | LlmContentBlock[] , seq, ... }
- * // run.status: "idle" | "running" | "completed" | "failed"
+ * // run.status: "idle" | "running" | "completed" | "failed" | "cancelled"
  * // run.streamId: attach to live tokens with resumeStream(run.streamId)
+ * // run.pendingInput: messages sent mid-generation, not yet drained
  * ```
  *
  * Start or continue a run with `streamFn("<agentName>", { input, runId? })`
  * — tokens stream on that connection; the persisted transcript arrives
- * here.
+ * here. Sending while the run is generating queues the message rather
+ * than failing, so the composer stays live. Stop a run with
+ * `cancelAgentRun(agentName, runId)`.
  */
 export interface AgentRunRow {
     id: string;
     agent: string;
-    status: "idle" | "running" | "completed" | "failed" | string;
+    status: "idle" | "running" | "completed" | "failed" | "cancelled" | string;
     userId?: string | null;
     title?: string | null;
     /** Resumable-stream id of the current/last generation. */
     streamId?: string | null;
     error?: string | null;
+    /** Messages sent while the agent was generating, not yet folded into
+     *  the transcript. Render these as queued below the last message. */
+    pendingInput?: string[] | null;
+    /** A cancel has been asked for and the loop has not reached the
+     *  boundary where it stops. Drive the stop button's pending state
+     *  from this. */
+    cancelRequested?: boolean | null;
+    /** Cumulative model↔tool round-trips across every turn of this run. */
+    steps?: number | null;
     createdAt: string;
     updatedAt: string;
 }

package/package.json

@@ -3,7 +3,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.4.27",
+  "version": "0.4.28",
   "type": "module",
   "main": "./src/index.ts",
   "types": "./dist/index.d.ts",
@@ -14,8 +14,8 @@
     "prepack": "bun run build"
   },
   "dependencies": {
-    "@pylonsync/sdk": "0.4.27",
-    "@pylonsync/sync": "0.4.27"
+    "@pylonsync/sdk": "0.4.28",
+    "@pylonsync/sync": "0.4.28"
   },
   "peerDependencies": {
     "react": ">=19.0.0"

package/src/index.ts

@@ -525,6 +525,41 @@ export async function callFn<T = unknown>(
   );
 }
 
+/**
+ * Ask an `agent()` run to stop.
+ *
+ * Cancel is durable, not a stream teardown: it lands on the run row,
+ * so it reaches a loop running on a different machine, and abandoning
+ * the SSE connection is NOT a cancel (a detached cloud run is supposed
+ * to survive the window closing).
+ *
+ * The call returns as soon as the request is recorded. A live
+ * generation stops at its next turn boundary — between tool calls
+ * within seconds, or after the current model response finishes.
+ * `run.cancelRequested` is true in that window; drive the stop
+ * button's pending state from it and treat `run.status === "cancelled"`
+ * as the confirmation.
+ *
+ * ```ts
+ * const { run } = useAgentRun(runId);
+ * <button
+ *   disabled={run?.cancelRequested === true}
+ *   onClick={() => cancelAgentRun("helper", runId)}
+ * >Stop</button>
+ * ```
+ */
+export async function cancelAgentRun(
+  agentName: string,
+  runId: string,
+  options: { token?: string } = {},
+): Promise<{ runId: string; cancelled: boolean }> {
+  return callFn<{ runId: string; cancelled: boolean }>(
+    agentName,
+    { runId, cancel: true },
+    options,
+  );
+}
+
 /** Options for {@link streamFn}. */
 export interface StreamFnOptions {
   token?: string;