@sublang/playbook 0.9.0 → 1.3.0

package/slc/optimize.md

@@ -0,0 +1,92 @@
+<!-- SPDX-License-Identifier: Apache-2.0 -->
+<!-- SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai> -->
+
+# GEARS Optimization Pass
+
+Optional optimization pass of a playbook (a state-machine agent orchestrating other agents).
+Rewrites deterministic mechanical behaviors into
+[script behaviors](text2gears.md#script-behaviors-optimizer-introduced) so the
+compiled playbook performs them directly, without an agent call.
+
+- Source: a package of GEARS spec items produced by [text2gears](text2gears.md).
+- Target: the same package with eligible items rewritten as script items.
+
+The pass is format-preserving: source and target are both GEARS packages, and
+the pass sits between [text2gears](text2gears.md) and
+[gears2fsm](gears2fsm.md) only when the compile requests optimization.
+A playbook compiled without this pass has identical observable behavior; the
+pass trades a compile-time rewrite for cheaper, deterministic runtime steps.
+
+## Formats
+
+| Role   | Format | Extension |
+| ------ | ------ | --------- |
+| source | gears  | .md       |
+| target | gears  | .md       |
+
+## Eligibility
+
+The pass shall rewrite an item only when **all** of the following hold:
+
+- The item's behavior is mechanical: a fixed shell command performs it
+  completely, with no judgment, no natural-language generation, and no
+  reading of conversational context.
+- The command is static: it needs no `<placeholder>` and no runtime value
+  beyond the working directory the runtime executes in.
+- No other item's condition or prompt consumes prose this item's acting agent
+  would have produced; the item's effect is entirely on the environment
+  (files, repository state, directories) plus a success/failure signal.
+- The item's outcome contract collapses to a two-way split decidable by the
+  command's exit status. An item whose declared `Results:` distinguish more
+  than success/failure, or whose outcomes require extracted output fields,
+  is ineligible.
+
+The canonical example is environment setup, such as ensuring the working
+directory is a version-control repository before committing to it:
+`git rev-parse --is-inside-work-tree 2>/dev/null || git init`.
+
+Judgment stays conservative: when eligibility is uncertain, the pass shall
+leave the item unchanged rather than guess.
+The pass shall not invent items, commands stronger than the item's stated
+behavior, or requirements the source does not state.
+
+## Rewriting
+
+For each eligible item, the pass shall:
+
+- Keep the item's ID, heading form, and condition text unchanged.
+- Replace the acting clause with the literal script form `Captain shall run:`.
+  Like guard names, the script clause is fixed machine syntax [[1]] and
+  stays in this exact English form even when the surrounding item text is
+  in another language.
+- Replace the blockquoted prompt with the exact POSIX shell script that
+  performs the behavior, static text only.
+- Emit exactly two `Results:` bullets per
+  [text2gears "Script behaviors"](text2gears.md#script-behaviors-optimizer-introduced):
+  first the zero-exit guard, then the nonzero-exit guard. When the original
+  item declared exactly two guards that align with success and failure, keep
+  those guard names in that order; otherwise use `ok` and `failed`.
+- Preserve every other item and every non-item section byte-for-byte.
+
+Target shall be written in the same language as Source: rewritten conditions
+and result descriptions stay in the source language; only guard names and the
+shell script are language-independent.
+
+## Provenance
+
+The pass shall append one `## Optimizations` section at the end of the target
+listing every rewritten item, one bullet per item:
+`- <ITEM-ID>: <original behavior kind> → script`.
+When no item is eligible, the target shall be the source content unchanged,
+with no `## Optimizations` section.
+
+## Out of scope
+
+- Rewriting captain, player, or nested-playbook behaviors into one another.
+- Reordering, merging, splitting, or deleting items.
+- Any change to prompts, conditions, or result contracts of items the pass
+  does not rewrite.
+
+## References
+
+[1]: GEARS definition shipped by the installed `@sublang/spex` package: `@sublang/spex/scaffold/specs/meta.md` (English) and `@sublang/spex/scaffold/i18n/zh/specs/meta.md` (Chinese); canonical renditions [GEARS: AI-Ready Spec Syntax](https://sublang.ai/ref/gears-ai-ready-spec-syntax) (en) and [GEARS：面向 AI 的规约语法](https://sublang.ai/zh/ref/gears-ai-ready-spec-syntax) (zh)

package/slc/text2gears.md

@@ -13,10 +13,10 @@ The second phase (spec items → state machine) is out of scope.
 
 ## Formats
 
-| Role | Format | Extension |
-| --- | --- | --- |
-| source | text | .md |
-| target | gears | .md |
+| Role   | Format | Extension |
+| ------ | ------ | --------- |
+| source | text   | .md       |
+| target | gears  | .md       |
 
 ## Players
 
@@ -39,8 +39,50 @@ Capitalize English player names (e.g., `Writer`); quote non-English names (e.g.,
 
 ## Behaviors
 
-Each spec item names a condition, the player to prompt, and the prompt itself.
+Each spec item names a condition, one behavior kind, and the complete prompt
+for that behavior.
+Every emitted item shall use the exact Markdown heading form `### <ITEM-ID>`.
+An item heading at `##`, `####`, or another level is not GEARS item syntax and
+will not be visible to downstream compilers or verification.
+The behavior kind shall be one of:
+
+- direct Captain work, written `Captain shall <behavior>:` without naming a
+  delegated player;
+- delegated player work, written `Captain shall prompt <Player>:` or the
+  existing `Captain shall relay ... to <Player> ...:` form; or
+- a literal or dynamic nested playbook call as defined below.
+
+Direct Captain work means the coordinating Captain performs the behavior
+itself. It shall not be rewritten as `Captain shall prompt Captain`, because
+Captain is a distinct runtime actor rather than a player binding.
+Delegated work shall name the declared player that receives the prompt.
 Prompts shall be blockquoted, one point per line.
+When Source already supplies the complete blockquoted acting prompt for a
+behavior, text2gears shall preserve those prompt lines exactly (apart from the
+documented Markdown unescaping) and shall not promote surrounding conditions,
+invariants, result fields, or continuation mechanics into that blockquote.
+Those requirements remain in the item's condition or `Results:` metadata.
+Adding control-oriented prompt lines merely to restate them changes the
+Boss-visible contract and is nonconformant.
+
+Source statements that assign active-leaf routing, call identity, suspension,
+or return matching to the host describe execution preconditions rather than
+behaviors for Captain to perform. text2gears shall use such a statement only as
+a condition on an actual behavior when needed and shall not emit a standalone
+direct-Captain item that asks Captain to implement host stack bookkeeping.
+The same applies to a host-owned input catalog's immutability: retain it as a
+condition/invariant on the behaviors that consume the catalog, never as an LLM
+action that can replace or mutate host configuration.
+Opening source invariants consumed by later behaviors shall remain explicit in
+the emitted conditions or prompts rather than being summarized away. In
+particular, preserve the declared exact entry shape of a structured host
+catalog and any progress invariant that makes a decide-call-observe plan
+finite, such as `remainingPlan` containing only calls after the selected call
+and strictly shrinking on continuation.
+Likewise, a source invariant that restricts a nested-call target to a
+non-empty member of an input catalog is a condition on that call item, not a
+separate Captain rejection behavior, unless Source requires an observable
+response distinct from taking or skipping the call.
 
 E.g.:
 
@@ -48,13 +90,217 @@ E.g.:
 ### CODE-10
 
 When Reviewer is about to review any change, Captain shall prompt Reviewer:
+
 > Flag any issues or improvements (numbered; no duplication).
 > Think thoroughly — don't just approve or reject.
 > If the change is ready to commit or push, don't raise nitpicks.
 > Do not edit files or commit; report findings only.
 ```
 
-Target should be written in the same language as Source.
+Direct Captain example:
+
+```markdown
+### ROUTE-1
+
+When Boss gives an intent, Captain shall decide how to handle it:
+
+> Preserve Boss's intended outcome and constraints.
+> Ask one question only when its answer would materially change routing.
+```
+
+### Result contracts
+
+When Source gives an acting behavior more than one possible outcome,
+text2gears shall emit its machine-facing result contract immediately after the
+complete blockquote, outside the acting prompt, in this exact form:
+
+```markdown
+Results:
+- `question`: Captain asked one material question. Output shall include `question: <verbatim final text>`.
+- `delegation`: Captain selected a call. Output shall include `remainingPlan: <JSON-safe array>`, `nextPlaybookId: <stable id>`, and `nextPlaybookInput: <complete request>`.
+```
+
+`Results:` shall be a plain label rather than a heading.
+Every result shall occupy one bullet with exactly a backtick-delimited guard
+name, a colon, and a non-empty description.
+The guard name shall match the ASCII identifier pattern
+`[A-Za-z_$][A-Za-z0-9_$]*`.
+The bullet order is authoritative, guard names are unique within the item, and
+the description shall name every required output property with its exact
+case-sensitive identifier.
+
+A produced value consumed later shall have a declared producer: where any
+later item's blockquote reads a value through a `<placeholder>`, the item
+whose behavior produces that value shall declare the `Results:` contract
+whose relevant description names the produced output property, using the
+placeholder's exact identifier — this is what lets the FSM thread the value
+through typed context.
+A single-outcome producer then declares exactly one bullet naming the
+property; this consumed-output case is the sole one in which a
+single-outcome behavior carries a `Results:` label.
+
+Result metadata is compiler control data, not part of the acting agent's
+prompt.
+text2gears shall not put guard names, result-property schema, JSON control
+instructions, or adjudicator instructions inside the blockquote unless Source
+explicitly requires the acting agent to show that machine syntax to the user.
+It shall move Source's outcome contract into `Results:` while preserving the
+human domain instructions in the blockquote.
+It shall not emit the framework-owned `needsBossReply` result; gears2fsm adds
+that universal result for every Captain- or player-invoking state.
+
+Where Source restricts an initial Captain to routing, text2gears shall preserve
+only the authored question and delegation outcomes and shall not infer a
+direct-answer or terminal result merely because Captain is the acting agent.
+
+A single-outcome behavior whose output no later item consumes carries no
+`Results:` label; downstream,
+[gears2fsm](gears2fsm.md#setup) gives its state the default single-outcome
+contract, so text2gears shall not invent a one-bullet `Results:` block for it.
+When a later item does consume its output, the produced-value rule above
+applies instead.
+
+### Boss-reply continuation
+
+Where a direct-Captain or delegated-player behavior may ask Boss a question
+and wait, Boss's answer resumes that same behavior with continuation context;
+it is not a distinct behavior item. text2gears shall keep the question result,
+the wait, and the answer-dependent continuation on the originating item even
+when the answer changes its complete runtime prompt. It shall not emit a
+second item solely for "Boss answers," "after the question," or clearing the
+consumed question/reply. The FSM and linker own the same-leaf suspension,
+continuation blocks, and consumed-context cleanup.
+
+This rule is an exception to splitting by accumulated prompt content below.
+Split only when Source requires a genuinely different acting behavior after
+the reply, not when the same decision or task continues with Boss's answer.
+
+The same consolidation applies when Source says a fresh directive interrupts
+parked work and *restarts the same behavior* with cleared context. When the
+acting prompt and result contract are identical, retain the interrupt as an
+entry condition on the originating item; do not duplicate that item solely to
+describe the restart. Split only when the fresh directive invokes genuinely
+different acting work or a different prompt/result contract.
+
+### Parallel behaviors
+
+Where two or more delegated-player items share one trigger and Source requires
+them to run independently before later work uses all results, text2gears shall
+place `Parallel group: <stable-kebab-case-id>` immediately below each item
+heading.
+Every item in one parallel group shall receive the same completed-prior-group
+inputs; no item prompt may depend on another member's result from the current
+group.
+Every member shall delegate to a named player, and the source shall permit
+those members to resolve to distinct players. Direct-Captain work shares one
+Captain session and nested calls share one pending-child stack slot, so neither
+kind may receive parallel-group metadata. If Source explicitly requires either
+unsupported kind to run concurrently, text2gears shall report that the source
+cannot be represented rather than silently serialize it or emit metadata the
+next phase cannot compile.
+
+Example:
+
+```markdown
+### DISCUSS-1
+
+Parallel group: initial-proposals
+
+When Boss gives a topic, Captain shall prompt Host:
+
+> Propose your design independently.
+```
+
+### Nested playbook calls
+
+Where Source requires one playbook to call a statically known playbook,
+text2gears shall emit an item whose behavior uses
+`Captain shall call playbook <playbook-id>:` and whose blockquote is the
+complete JSON-safe input-text template for that call.
+The literal target id shall be a stable configured playbook id, not a slash
+command or module specifier.
+
+Example:
+
+```markdown
+### RELEASE-8
+
+When implementation is ready for review, Captain shall call playbook `code-review`:
+
+> Review these changes:
+> <changes>
+```
+
+Where Source selects the target at runtime, text2gears shall instead emit the
+first-class dynamic form
+``Captain shall call playbook selected by `<playbook-id-context>`:``.
+The backtick-delimited name identifies a typed FSM context field whose runtime
+value is the target playbook id; it is not itself a target id.
+The blockquote shall be exactly one placeholder naming the typed context field
+whose runtime string is the complete child input text.
+
+Example:
+
+```markdown
+### CAPTAIN-2
+
+When Captain selects a next call, Captain shall call playbook selected by `nextPlaybookId`:
+
+> <nextPlaybookInput>
+```
+
+Here `nextPlaybookId` and `nextPlaybookInput` are stable context-field names.
+The dynamic form shall not use a slash command, module specifier, opaque
+expression, or prose from which a downstream compiler would have to infer
+either field.
+
+### Script behaviors (optimizer-introduced)
+
+A GEARS package may also contain deterministic script behaviors, written
+`Captain shall run:` followed by a blockquote whose lines are the exact POSIX
+shell script to execute.
+text2gears shall never emit this kind: script items enter a GEARS package only
+through the separate [optimize](optimize.md) pass, which rewrites eligible
+compiled items.
+The kind is defined here so every consumer of the GEARS format shares one
+item-syntax contract.
+
+A script item's blockquote is static shell text: it shall contain no
+`<placeholder>`, and Markdown escapes resolve exactly as in acting prompts.
+A script item shall carry a `Results:` label with exactly two bullets in this
+fixed interpretation: the first guard reports the script exiting with status
+zero, the second reports a nonzero exit status.
+No other result, and no `needsBossReply`, applies to a script item — a script
+has no agent to surface questions.
+
+Example:
+
+```markdown
+### CODE-1
+
+When the workflow starts, Captain shall run:
+
+> git rev-parse --is-inside-work-tree 2>/dev/null || git init
+
+Results:
+- `ok`: The command exited with status zero.
+- `failed`: The command exited with a nonzero status.
+```
+
+Target shall be written in the same language as Source: an item's condition
+prose, acting prompts, and result descriptions follow the Source language,
+read per the matching localization of the GEARS definition [[1]].
+The four `Captain shall` acting-clause forms defined above (direct,
+delegated, nested playbook call, and script), guard names, and the
+`Players:` and `Results:` labels are fixed machine syntax and stay in this
+exact English form regardless of Source language.
+
+## Transformation-spec sources
+
+A Source may itself be the normative specification of a transformation — e.g., a compiler phase definition, as when a meta pipeline compiles this file.
+Such a Source declares no players and prompts none; its implied procedure is that Captain performs the specified transformation on request.
+Compose Captain-acting spec items for it: when a transformation request names the specification's source and target, Captain shall carry out the transformation as specified.
+Prompts shall carry the specification's normative requirements as instructions to Captain — deduplicated, one point per line — without inventing players, triggers, or requirements the specification does not state.
 
 ## Composition
 
@@ -71,6 +317,8 @@ Test: a human shall be able to simulate a run by copying any single item's promp
 Use `<placeholder>` for dynamic values in blockquoted prompts.
 Everything else inside a blockquote is static text, not an example; examples belong in surrounding prose.
 
+Markdown escaping is Source syntax, not content: extraction shall resolve escapes (e.g. `\<placeholder\>` becomes `<placeholder>`), so compiled artifacts carry plain text.
+
 ### Split by content discriminator
 
 Partition items by every variable that determines prompt content — including accumulated state when the trigger alone doesn't.
@@ -82,4 +330,4 @@ Dead branches mislead readers and downstream phases.
 
 ## References
 
-[1]: [GEARS syntax](/specs/meta.md#item-syntax)
+[1]: GEARS definition shipped by the installed `@sublang/spex` package: `@sublang/spex/scaffold/specs/meta.md` (English) and `@sublang/spex/scaffold/i18n/zh/specs/meta.md` (Chinese); canonical renditions [GEARS: AI-Ready Spec Syntax](https://sublang.ai/ref/gears-ai-ready-spec-syntax) (en) and [GEARS：面向 AI 的规约语法](https://sublang.ai/zh/ref/gears-ai-ready-spec-syntax) (zh)

package/src/runtime.d.ts

@@ -1,23 +1,166 @@
 export interface PlayerResult {
     status: 'ok' | 'aborted' | 'error';
+    resumeToken?: string;
     finalText?: string;
     error?: string;
 }
+export interface PlayerCallOptions {
+    resume: string | false;
+}
+export interface CaptainCallOptions {
+    visibility: 'visible' | 'hidden';
+    resume: string | false;
+    allowedTools?: readonly string[];
+}
+export interface CaptainResult {
+    status: 'ok' | 'aborted' | 'error';
+    finalText?: string;
+    error?: string;
+}
+export type JsonValue = null | boolean | number | string | readonly JsonValue[] | {
+    readonly [key: string]: JsonValue;
+};
+export interface NormalizedError {
+    name: string;
+    message: string;
+    stack?: string;
+}
+export type PlaybookStateValue = string | {
+    readonly [key: string]: PlaybookStateValue;
+};
+export interface PlaybookState {
+    value: PlaybookStateValue;
+    activeStateIds: readonly string[];
+    tags: readonly string[];
+    status: 'active' | 'done' | 'error' | 'stopped';
+    quiescent: boolean;
+    stateId?: string;
+}
+export interface PlaybookPendingCall {
+    callId: string;
+    playbookId: string;
+    childSessionId: string;
+}
+export interface PlaybookCallRequest {
+    callId: string;
+    playbookId: string;
+    text: string;
+}
+export type PlaybookCallResult = {
+    status: 'ok';
+    playbookId: string;
+    childSessionId: string;
+    state?: PlaybookState;
+    output?: JsonValue;
+} | {
+    status: 'aborted';
+    playbookId: string;
+    childSessionId?: string;
+    state?: PlaybookState;
+    error?: NormalizedError;
+} | {
+    status: 'error';
+    playbookId: string;
+    childSessionId?: string;
+    state?: PlaybookState;
+    error: NormalizedError;
+};
+export type PlaybookCallStart = {
+    state: 'settled';
+    result: PlaybookCallResult;
+} | {
+    state: 'suspended';
+    childSessionId: string;
+};
+export type PlaybookRunResult = {
+    outcome: 'quiescent' | 'no-action';
+    state: PlaybookState;
+} | {
+    outcome: 'failed' | 'aborted';
+    state: PlaybookState;
+    error?: NormalizedError;
+} | {
+    outcome: 'terminal';
+    state: PlaybookState;
+    output?: JsonValue;
+} | {
+    outcome: 'suspended';
+    state: PlaybookState;
+    pendingCall: PlaybookPendingCall;
+};
 export interface PlaybookPorts {
-    callPlayer(playerId: string, prompt: string, signal: AbortSignal): Promise<PlayerResult>;
+    callPlayer(playerId: string, prompt: string, signal: AbortSignal, options: PlayerCallOptions): Promise<PlayerResult>;
+    callCaptain(prompt: string, signal: AbortSignal, options: CaptainCallOptions): Promise<CaptainResult>;
     callJudge(prompt: string, signal: AbortSignal): Promise<string>;
+    callPlaybook(request: PlaybookCallRequest, signal: AbortSignal): Promise<PlaybookCallStart>;
     emitStatus(message: string, data?: unknown): Promise<void>;
     emitTelemetry(event: {
         topic: string;
         payload: unknown;
     }): Promise<void>;
 }
+export interface PlaybookSession {
+    sessionId: string;
+    playbookId: string;
+    rootSessionId: string;
+    parentSessionId?: string;
+    parentCallId?: string;
+    depth: number;
+    ports: PlaybookPorts;
+}
+export type PlaybookTraceType = 'session.started' | 'boss.input.received' | 'judge.call.started' | 'judge.call.finished' | 'player.call.started' | 'player.call.finished' | 'captain.call.started' | 'captain.call.finished' | 'playbook.call.started' | 'playbook.call.finished' | 'fsm.transition' | 'status.emitted' | 'boss.input.settled' | 'session.disposed';
+export interface PlaybookTraceEvent {
+    schemaVersion: 2;
+    sessionId: string;
+    playbookId: string;
+    rootSessionId: string;
+    parentSessionId?: string;
+    parentCallId?: string;
+    depth: number;
+    sequence: number;
+    timestamp: number;
+    type: PlaybookTraceType;
+    turnId?: number;
+    callId?: string;
+    payload: JsonValue;
+}
+export interface PlaybookPendingBossQuestion {
+    questionId: string;
+    player: string;
+    question: string;
+    sourceItem?: string;
+}
+export interface PlaybookRuntimeSnapshot {
+    schemaVersion: 1;
+    playbookId: string;
+    machine: JsonValue;
+    playerResumeTokens: {
+        readonly [playerId: string]: string;
+    };
+    sequences: {
+        trace: number;
+        turn: number;
+        judgeCall: number;
+        playerCall: number;
+        playbookCall: number;
+        captainCall?: number;
+    };
+    state: PlaybookState;
+    pendingBossQuestions: readonly PlaybookPendingBossQuestion[];
+}
 export interface PlaybookRuntime {
-    init(ports: PlaybookPorts): Promise<void>;
+    init(session: PlaybookSession): Promise<void>;
+    exportSnapshot?(): PlaybookRuntimeSnapshot | undefined;
+    restore?(session: PlaybookSession, snapshot: PlaybookRuntimeSnapshot): Promise<void>;
     handleBossInput(turn: {
         text: string;
         signal: AbortSignal;
-    }): Promise<void>;
+    }): Promise<PlaybookRunResult>;
+    resumePlaybookCall(input: {
+        callId: string;
+        result: PlaybookCallResult;
+        signal: AbortSignal;
+    }): Promise<PlaybookRunResult>;
     dispose(): Promise<void>;
 }
 export type PlaybookRuntimeFactory<Options = unknown> = (options: Options) => PlaybookRuntime;