@skillstate/core 2.0.3 → 2.0.5

package/README.md

@@ -6,7 +6,7 @@
 
 [![npm version](https://img.shields.io/npm/v/@skillstate/core)](https://www.npmjs.com/package/@skillstate/core)
 [![node](https://img.shields.io/node/v/@skillstate/core)](https://www.npmjs.com/package/@skillstate/core)
-[![Tests](https://img.shields.io/badge/tests-755%20passing-brightgreen)](https://github.com/vitalykuzyaev/skillstate)
+[![Tests](https://img.shields.io/badge/tests-873%20passing-brightgreen)](https://github.com/vitalykuzyaev/skillstate)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/vitalykuzyaev/skillstate/blob/main/LICENSE)
 
 </div>

package/dist/instrumentation.d.ts

@@ -14,7 +14,7 @@ export interface TokenCounter {
     count(text: string): number;
 }
 /**
- * @non-paper legacy heuristic: 1 token ≈ 4 chars, rounded up.
+ * @non-paper rough heuristic: 1 token ≈ 4 chars, rounded up.
  *
  * Kept for backward compatibility of ad-hoc estimates only. Do NOT use it
  * for paper §4.3 metrics — those are measured in chars (see `TokenTracker`).

package/dist/instrumentation.js

@@ -9,7 +9,7 @@
  * paper-exact baseline in `./token-tracker.js`.
  */
 /**
- * @non-paper legacy heuristic: 1 token ≈ 4 chars, rounded up.
+ * @non-paper rough heuristic: 1 token ≈ 4 chars, rounded up.
  *
  * Kept for backward compatibility of ad-hoc estimates only. Do NOT use it
  * for paper §4.3 metrics — those are measured in chars (see `TokenTracker`).

package/dist/provider.d.ts

@@ -8,10 +8,10 @@
  * - `LLMProvider.call(prompt, opts?)` resolves `{ text, usage? }` where
  *   `usage.promptChars` / `usage.completionChars` are RAW STRING CHARS
  *   (§4.3) reported by the caller — never tokenizer output;
- * - `fromLLMFn(fn)` wraps a legacy `LLMFn` into an `LLMProvider`
+ * - `fromLLMFn(fn)` wraps a plain `LLMFn` function into an `LLMProvider`
  *   (backwards compatibility; `LLMFn` itself is NOT removed);
  * - `isLLMProvider(v)` distinguishes `LLMFn | LLMProvider` at runtime
- *   (function = legacy fn, object with a `call` function = provider).
+ *   (plain function = fn form, object with a `call` function = provider).
  *
  * The runtime accepts `llm: LLMFn | LLMProvider`: with a provider it
  * prefers `usage` over measuring strings, otherwise it measures exactly
@@ -27,7 +27,7 @@ export interface LLMCallOptions {
 /**
  * @non-paper usage reported by the provider, in raw string CHARS (§4.3).
  * Both fields are optional: missing values fall back to measuring the
- * corresponding string, exactly the legacy `LLMFn` behavior.
+ * corresponding string, exactly the plain `LLMFn` behavior.
  */
 export interface LLMUsage {
     /** Raw chars of the prompt as sent (overrides `prompt.length`). */
@@ -49,11 +49,11 @@ export interface LLMProvider {
 }
 /**
  * @non-paper runtime guard: an object with a callable `call` is a
- * provider; anything else passed as `llm` is treated as a legacy `LLMFn`.
+ * provider; anything else passed as `llm` is treated as a plain `LLMFn`.
  */
 export declare function isLLMProvider(value: unknown): value is LLMProvider;
 /**
- * @non-paper backwards-compatibility adapter: wrap a legacy `LLMFn`
+ * @non-paper adapter: wrap a plain `LLMFn` function
  * into an `LLMProvider`. The wrapper honors an already-aborted `signal`
  * (rejects with `signal.reason`) and otherwise delegates verbatim —
  * no usage is synthesized, so the runtime measures strings as before.

package/dist/provider.js

@@ -8,10 +8,10 @@
  * - `LLMProvider.call(prompt, opts?)` resolves `{ text, usage? }` where
  *   `usage.promptChars` / `usage.completionChars` are RAW STRING CHARS
  *   (§4.3) reported by the caller — never tokenizer output;
- * - `fromLLMFn(fn)` wraps a legacy `LLMFn` into an `LLMProvider`
+ * - `fromLLMFn(fn)` wraps a plain `LLMFn` function into an `LLMProvider`
  *   (backwards compatibility; `LLMFn` itself is NOT removed);
  * - `isLLMProvider(v)` distinguishes `LLMFn | LLMProvider` at runtime
- *   (function = legacy fn, object with a `call` function = provider).
+ *   (plain function = fn form, object with a `call` function = provider).
  *
  * The runtime accepts `llm: LLMFn | LLMProvider`: with a provider it
  * prefers `usage` over measuring strings, otherwise it measures exactly
@@ -19,7 +19,7 @@
  */
 /**
  * @non-paper runtime guard: an object with a callable `call` is a
- * provider; anything else passed as `llm` is treated as a legacy `LLMFn`.
+ * provider; anything else passed as `llm` is treated as a plain `LLMFn`.
  */
 export function isLLMProvider(value) {
     if (typeof value !== 'object' || value === null) {
@@ -28,7 +28,7 @@ export function isLLMProvider(value) {
     return typeof value.call === 'function';
 }
 /**
- * @non-paper backwards-compatibility adapter: wrap a legacy `LLMFn`
+ * @non-paper adapter: wrap a plain `LLMFn` function
  * into an `LLMProvider`. The wrapper honors an already-aborted `signal`
  * (rejects with `signal.reason`) and otherwise delegates verbatim —
  * no usage is synthesized, so the runtime measures strings as before.

package/dist/runtime.d.ts

@@ -183,7 +183,7 @@ export declare class SkillStateRuntime {
     /**
      * @non-paper LLM dispatch (Wave 4 DX, additive).
      *
-     * Paper path: `llm` is a legacy `LLMFn` — called verbatim with the
+     * Paper path: `llm` is a plain `LLMFn` function — called verbatim with the
      * prompt, exactly as before. Provider path: `llm.call(prompt, opts?)`
      * is used instead, forwarding the runtime `signal?` so aborts reach
      * the provider; both paths stay inside `invokeResilient`, so the

package/dist/runtime.js

@@ -134,7 +134,7 @@ export class SkillStateRuntime {
     /**
      * @non-paper LLM dispatch (Wave 4 DX, additive).
      *
-     * Paper path: `llm` is a legacy `LLMFn` — called verbatim with the
+     * Paper path: `llm` is a plain `LLMFn` function — called verbatim with the
      * prompt, exactly as before. Provider path: `llm.call(prompt, opts?)`
      * is used instead, forwarding the runtime `signal?` so aborts reach
      * the provider; both paths stay inside `invokeResilient`, so the

package/dist/schemas/generic-procedure.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Default neutral spec for `skillstate init` — domain-agnostic state-based
+ * execution. Projects differ; the task spec is the user's concern
+ * (`skillstate init --spec <path>`). This schema only fixes the universal
+ * bookkeeping fields every stateful procedure needs.
+ *
+ * The CTF example remains available explicitly via `skillstate init --example ctf`.
+ */
+import type { ProceduralSpec } from '../types.js';
+export declare const GENERIC_PROCEDURE_SPEC: ProceduralSpec;
+//# sourceMappingURL=generic-procedure.d.ts.map

package/dist/schemas/generic-procedure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generic-procedure.d.ts","sourceRoot":"","sources":["../../src/schemas/generic-procedure.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,eAAO,MAAM,sBAAsB,EAAE,cA8DpC,CAAC"}

package/dist/schemas/generic-procedure.js

@@ -0,0 +1,64 @@
+export const GENERIC_PROCEDURE_SPEC = {
+    id: 'generic-procedure',
+    name: 'State-based Execution',
+    version: '1.0.0',
+    instructions: [
+        'You are operating in state-based execution mode on an arbitrary task.',
+        '',
+        'Your execution state is persisted externally and restored between',
+        'steps. Conversation history is trimmed automatically: never rely on',
+        'it to carry information. Anything you need later MUST go into',
+        'state_patch this step.',
+        '',
+        'Process for every step:',
+        '1. Read the current state and the latest observation.',
+        '2. Reason about the single next action that makes the most progress',
+        '   toward the goal.',
+        '3. Emit a JSON block with exactly two keys:',
+        '   { "state_patch": { ... }, "action": "<what you are doing next>" }',
+        '',
+        'State discipline:',
+        '- Keep `goal` accurate; refine it as understanding improves.',
+        '- Move finished work into `progress`; keep `next_steps` current.',
+        '- Record produced or modified files in `artifacts`.',
+        '- Track unknowns and obstacles in `blockers` instead of memory.',
+        '- Use `notes` for anything else worth persisting.',
+        '- Set a key to null in state_patch to delete it.',
+        '',
+        'Iterate observation -> reasoning -> state_patch -> action until the',
+        'goal is achieved and `progress` reflects it.',
+    ].join('\n'),
+    schema: {
+        goal: {
+            type: 'string',
+            default: '',
+            description: 'What the current procedure is trying to achieve',
+        },
+        progress: {
+            type: 'array',
+            default: [],
+            description: 'Completed steps or milestones',
+        },
+        next_steps: {
+            type: 'array',
+            default: [],
+            description: 'Planned next actions',
+        },
+        artifacts: {
+            type: 'array',
+            default: [],
+            description: 'Files or paths produced or modified so far',
+        },
+        blockers: {
+            type: 'array',
+            default: [],
+            description: 'Current obstacles or unknowns',
+        },
+        notes: {
+            type: 'string',
+            default: '',
+            description: 'Free-form working notes persisted between steps',
+        },
+    },
+};
+//# sourceMappingURL=generic-procedure.js.map

package/dist/schemas/generic-procedure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generic-procedure.js","sourceRoot":"","sources":["../../src/schemas/generic-procedure.ts"],"names":[],"mappings":"AAUA,MAAM,CAAC,MAAM,sBAAsB,GAAmB;IACpD,EAAE,EAAE,mBAAmB;IACvB,IAAI,EAAE,uBAAuB;IAC7B,OAAO,EAAE,OAAO;IAChB,YAAY,EAAE;QACZ,uEAAuE;QACvE,EAAE;QACF,mEAAmE;QACnE,qEAAqE;QACrE,+DAA+D;QAC/D,wBAAwB;QACxB,EAAE;QACF,yBAAyB;QACzB,uDAAuD;QACvD,qEAAqE;QACrE,qBAAqB;QACrB,6CAA6C;QAC7C,sEAAsE;QACtE,EAAE;QACF,mBAAmB;QACnB,8DAA8D;QAC9D,kEAAkE;QAClE,qDAAqD;QACrD,iEAAiE;QACjE,mDAAmD;QACnD,kDAAkD;QAClD,EAAE;QACF,qEAAqE;QACrE,8CAA8C;KAC/C,CAAC,IAAI,CAAC,IAAI,CAAC;IACZ,MAAM,EAAE;QACN,IAAI,EAAE;YACJ,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,EAAE;YACX,WAAW,EAAE,iDAAiD;SAC/D;QACD,QAAQ,EAAE;YACR,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,EAAE;YACX,WAAW,EAAE,+BAA+B;SAC7C;QACD,UAAU,EAAE;YACV,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,EAAE;YACX,WAAW,EAAE,sBAAsB;SACpC;QACD,SAAS,EAAE;YACT,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,EAAE;YACX,WAAW,EAAE,4CAA4C;SAC1D;QACD,QAAQ,EAAE;YACR,IAAI,EAAE,OAAO;YACb,OAAO,EAAE,EAAE;YACX,WAAW,EAAE,+BAA+B;SAC7C;QACD,KAAK,EAAE;YACL,IAAI,EAAE,QAAQ;YACd,OAAO,EAAE,EAAE;YACX,WAAW,EAAE,iDAAiD;SAC/D;KACF;CACF,CAAC"}

package/dist/schemas/index.d.ts

@@ -1,2 +1,3 @@
 export * from './intercode-ctf.js';
+export * from './generic-procedure.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/schemas/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AACA,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAEA,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC"}

package/dist/schemas/index.js

@@ -1,3 +1,5 @@
-// Canonical procedural specifications (paper §3.1 datasets).
+// Canonical procedural specifications (paper §3.1 datasets) plus the
+// neutral default used by `skillstate init` (domain-agnostic).
 export * from './intercode-ctf.js';
+export * from './generic-procedure.js';
 //# sourceMappingURL=index.js.map

package/dist/schemas/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/schemas/index.ts"],"names":[],"mappings":"AAAA,qEAAqE;AACrE,+DAA+D;AAC/D,cAAc,oBAAoB,CAAC;AACnC,cAAc,wBAAwB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillstate/core",
-  "version": "2.0.3",
+  "version": "2.0.5",
   "description": "Paper-exact skillstate runtime core (A.4 byte-verbatim formatPaper, §4.3 token tracker).",
   "type": "module",
   "main": "dist/index.js",