sh3-core 0.14.3 → 0.15.0

package/dist/verbs/types.d.ts

@@ -86,6 +86,49 @@ export interface VerbContext {
     fs: TenantFsClient;
     /** Invoke another registered verb programmatically (used by rich-entry clicks). */
     dispatch(line: string): Promise<void>;
+    /**
+     * When the verb was invoked via `ctx.runVerb(..., { structured })`,
+     * this holds the structured payload the caller passed. Terminal-driven
+     * invocations leave it undefined and the verb falls back to `args[]`.
+     * See `Verb.schema.input` for the JSON Schema describing the shape.
+     */
+    structuredArgs?: unknown;
+    /**
+     * When the verb was invoked via `ctx.runVerb(..., { signal })`, this
+     * carries the abort signal so cooperative verbs can honor cancellation.
+     * Terminal-driven invocations leave it undefined.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Portable JSON Schema subset accepted by sh3-core for `Verb.schema.input`.
+ * Documented as the intersection of what Anthropic, OpenAI, and Gemini
+ * tool-call APIs accept natively. sh3-core does NOT validate that the
+ * actual schema stays within this subset — authors who reach for `oneOf`,
+ * `$ref`, or other Draft 2020-12 features do so at their own portability
+ * risk. The type is intentionally `unknown`-permissive on `properties`
+ * and `items` so authors can express object/array shapes without
+ * fighting the type system.
+ */
+export interface PortableJSONSchema {
+    type?: 'string' | 'number' | 'integer' | 'boolean' | 'object' | 'array' | 'null';
+    description?: string;
+    enum?: unknown[];
+    default?: unknown;
+    /** Object-shape property map (key → sub-schema). */
+    properties?: Record<string, PortableJSONSchema>;
+    /** Required property names for `type: 'object'`. */
+    required?: string[];
+    /** Item schema for `type: 'array'`. */
+    items?: PortableJSONSchema;
+}
+/**
+ * Optional schema attached to a verb. Today only `input` is consumed
+ * (by sh3-ai's tool-call dispatcher); `output` is deferred until
+ * sh3-editor's graph view materializes a real consumer.
+ */
+export interface VerbSchema {
+    input: PortableJSONSchema;
 }
 export interface Verb {
     name: string;
@@ -98,6 +141,23 @@ export interface Verb {
      * `mode` switches modes — both make sense everywhere).
      */
     globalVerb?: boolean;
+    /**
+     * When true, this verb opts in to dispatch via `ctx.runVerb(...)`. By
+     * setting this flag the author commits to behaving correctly outside a
+     * real terminal frame — in particular, treating `ctx.scrollback` as a
+     * sink whose entries the caller may render later, and not depending on
+     * UI side-effects beyond what the synthesized context provides
+     * (no `ctx.session.connect()`, no terminal-mode switching, etc.).
+     * Defaults to false; `runVerb` rejects non-programmatic verbs.
+     */
+    programmatic?: boolean;
+    /**
+     * Optional input/output schema for typed callers. When present and the
+     * caller dispatches with `runVerb(..., { structured })`, the structured
+     * payload is delivered via `ctx.structuredArgs`; the verb chooses
+     * whether to read it or fall back to `args[]`.
+     */
+    schema?: VerbSchema;
     run(ctx: VerbContext, args: string[]): Promise<void>;
 }
 export type Resolution = {

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Auto-generated from package.json — do not edit manually. */
-export declare const VERSION = "0.14.3";
+export declare const VERSION = "0.15.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Auto-generated from package.json — do not edit manually. */
-export const VERSION = '0.14.3';
+export const VERSION = '0.15.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sh3-core",
-  "version": "0.14.3",
+  "version": "0.15.0",
   "type": "module",
   "files": [
     "dist"