@skillstate/core 2.0.0 → 2.0.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +183 -0
- package/package.json +4 -2
package/README.md
ADDED
|
@@ -0,0 +1,183 @@
|
|
|
1
|
+
<div align="center">
|
|
2
|
+
|
|
3
|
+
# @skillstate/core
|
|
4
|
+
|
|
5
|
+
**Paper-exact O(1) prompt-footprint runtime core — structured execution state instead of append-only conversation history.**
|
|
6
|
+
|
|
7
|
+
[](https://www.npmjs.com/package/@skillstate/core)
|
|
8
|
+
[](https://www.npmjs.com/package/@skillstate/core)
|
|
9
|
+
[](https://github.com/vitalykuzyaev/skillstate)
|
|
10
|
+
[](https://github.com/vitalykuzyaev/skillstate/blob/main/LICENSE)
|
|
11
|
+
|
|
12
|
+
</div>
|
|
13
|
+
|
|
14
|
+
---
|
|
15
|
+
|
|
16
|
+
`@skillstate/core` implements the **SKILL.state** runtime from the paper
|
|
17
|
+
[*SKILL.state: Scalable Long-Horizon Agent Skills*](https://arxiv.org/abs/2608.26263)
|
|
18
|
+
(arXiv:2608.26263). Instead of replaying an append-only transcript, an agent
|
|
19
|
+
maintains a fixed-schema execution state **Σₜ** that is read once per step and
|
|
20
|
+
patched between steps. The prompt footprint stays **O(1)** per step and the
|
|
21
|
+
cumulative cost drops to **O(T)**.
|
|
22
|
+
|
|
23
|
+
This package is the foundation of the `skillstate` monorepo: every adapter
|
|
24
|
+
(`@skillstate/claude`, `@skillstate/opencode`, `@skillstate/codex`,
|
|
25
|
+
`@skillstate/mcp`), plus the CLI and the benchmark harness, build on it. It
|
|
26
|
+
has **zero runtime dependencies** and ships TypeScript types.
|
|
27
|
+
|
|
28
|
+
## Installation
|
|
29
|
+
|
|
30
|
+
```bash
|
|
31
|
+
npm i @skillstate/core
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
Requires Node.js >= 20. The schema subpath `@skillstate/core/schemas` exports
|
|
35
|
+
the canonical InterCode CTF spec.
|
|
36
|
+
|
|
37
|
+
## Quick start
|
|
38
|
+
|
|
39
|
+
```ts
|
|
40
|
+
import { SkillStateRuntime, TokenTracker } from '@skillstate/core';
|
|
41
|
+
import { INTERCODE_CTF_SPEC } from '@skillstate/core/schemas';
|
|
42
|
+
import type { Observation } from '@skillstate/core';
|
|
43
|
+
|
|
44
|
+
const tracker = new TokenTracker({
|
|
45
|
+
platform: 'generic', // 'claude' | 'opencode' | 'generic'
|
|
46
|
+
sessionName: 'ctf-run-1',
|
|
47
|
+
});
|
|
48
|
+
|
|
49
|
+
const runtime = new SkillStateRuntime({
|
|
50
|
+
spec: INTERCODE_CTF_SPEC, // canonical 5-field CTF spec (paper §3.1)
|
|
51
|
+
llm: async (prompt) => {
|
|
52
|
+
// Your LLM call. The prompt asks for reasoning + a fenced JSON block
|
|
53
|
+
// with exactly two keys: state_patch and action.
|
|
54
|
+
return callYourLLM(prompt);
|
|
55
|
+
},
|
|
56
|
+
execute: async (action, state): Promise<Observation> => {
|
|
57
|
+
// Run the action (e.g. a bash command in a container) and return
|
|
58
|
+
// what the agent observes next.
|
|
59
|
+
const output = await runCommand(action);
|
|
60
|
+
return { content: output, timestamp: Date.now(), source: 'bash' };
|
|
61
|
+
},
|
|
62
|
+
tracker, // optional; records per-step §4.3 metrics
|
|
63
|
+
maxValidationRetries: 2, // optional; default 2 (max attempts = 3)
|
|
64
|
+
});
|
|
65
|
+
|
|
66
|
+
// One Algorithm 1 step:
|
|
67
|
+
const step = await runtime.step({ content: 'ls -la /', timestamp: Date.now(), source: 'bash' });
|
|
68
|
+
console.log(step.action); // the executed action
|
|
69
|
+
console.log(runtime.state); // Σₜ₊₁ (read-only copy)
|
|
70
|
+
console.log(step.reasoning); // returned to you, never stored in state
|
|
71
|
+
|
|
72
|
+
// Or run until done (default maxSteps: 100):
|
|
73
|
+
const results = await runtime.run(
|
|
74
|
+
{ content: 'Initial observation', timestamp: Date.now() },
|
|
75
|
+
(r) => (r.newState.discovered_flags as string[]).length > 0,
|
|
76
|
+
);
|
|
77
|
+
|
|
78
|
+
// §4.3 metrics (raw string chars, EXACTLY three fields):
|
|
79
|
+
const m = tracker.getMetrics();
|
|
80
|
+
console.log(m.averagePromptSize); // flat — that's the point
|
|
81
|
+
console.log(m.totalTokens); // cumulative char burn
|
|
82
|
+
console.log(m.accuracy); // accepted patches / actionable steps
|
|
83
|
+
console.log(tracker.compareWithBaseline().reductionFactor); // O(T²)→O(T)
|
|
84
|
+
tracker.save('./skillstate-report.json'); // full JSON report
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
A plausible `llm` response looks like:
|
|
88
|
+
|
|
89
|
+
````text
|
|
90
|
+
I should check for hidden files in /home first.
|
|
91
|
+
|
|
92
|
+
```json
|
|
93
|
+
{
|
|
94
|
+
"state_patch": { "working_dir": "/home", "active_files": [".bash_history"] },
|
|
95
|
+
"action": "cat /home/.bash_history"
|
|
96
|
+
}
|
|
97
|
+
```
|
|
98
|
+
````
|
|
99
|
+
|
|
100
|
+
## API / Exports
|
|
101
|
+
|
|
102
|
+
Everything is a named export from the root path `@skillstate/core`.
|
|
103
|
+
|
|
104
|
+
**Paper-exact core (Algorithm 1, §3–§4):**
|
|
105
|
+
|
|
106
|
+
- `SkillStateRuntime` — `new SkillStateRuntime(options: RuntimeOptions)`. Core
|
|
107
|
+
methods: `step(observation): Promise<StepResult>`,
|
|
108
|
+
`run(first, isDone, maxSteps?, runOpts?): Promise<StepResult[]>`, read-only
|
|
109
|
+
`state` getter. Implements Algorithm 1 with the §7 rollback-retry cycle;
|
|
110
|
+
rejected patches leave state untouched (rollback is free).
|
|
111
|
+
- `TokenTracker` — `new TokenTracker(config: TrackerConfig)`. `recordStep`,
|
|
112
|
+
`getMetrics()` (the §4.3 triad exactly), `getBookkeeping()`,
|
|
113
|
+
`compareWithBaseline()`, `exportReport()`, `save()`, `flush()`, `rotate()`,
|
|
114
|
+
`truncateTo()`, `load()`.
|
|
115
|
+
- `StateManager` — static `createInitialState`, `mergeState` (⊕
|
|
116
|
+
null-deletion merge, non-mutating), `validatePatch`, `serializeState`,
|
|
117
|
+
`deserializeState`; plus the `createStateManager()` factory.
|
|
118
|
+
- `PromptTransformer` — `formatPaper(spec, state, observation)` is the
|
|
119
|
+
**byte-verbatim** Appendix A.4 template; `formatPrompt`,
|
|
120
|
+
`formatForClaude`, `formatForOpenCode`, `extractStatePatch`,
|
|
121
|
+
`extractAction`, `parseResponse`, `serializeState`.
|
|
122
|
+
- Types: `SkillState`, `StatePatch`, `SchemaField`, `StateSchema`,
|
|
123
|
+
`ProceduralSpec`, `Observation`, `StateTransition`, `ValidationResult`,
|
|
124
|
+
`ExecutionStep`, `PlatformAdapter`, `TrackerConfig`, `LLMFn`,
|
|
125
|
+
`ActionExecutor`, `RuntimeOptions`, `StepResult`, `CharsBudget`,
|
|
126
|
+
`TokenBudget`, `RunOptions`, `BudgetExceededError`, `PaperMetrics`,
|
|
127
|
+
`BookkeepingMetrics`, `ParseResponseResult`, `ParseFailureReason`,
|
|
128
|
+
`PromptTransformerOptions`.
|
|
129
|
+
|
|
130
|
+
**Subpath `@skillstate/core/schemas`:** `INTERCODE_CTF_SPEC` — the canonical
|
|
131
|
+
5-field CTF spec (`discovered_flags`, `tested_hypotheses`, `active_files`,
|
|
132
|
+
`working_dir`, `cmd_summary`).
|
|
133
|
+
|
|
134
|
+
**`@non-paper` additive helpers (opt-in, not in the paper):**
|
|
135
|
+
|
|
136
|
+
- `instrumentation` — `CharDiv4Counter`, `estimateCostSavings` (heuristic
|
|
137
|
+
token/dollar estimates; `TokenCounter`).
|
|
138
|
+
- `resilience` — `withTimeout`, `withRetry`, `RetryOptions`, `CircuitBreaker`,
|
|
139
|
+
`CircuitBreakerOptions`, `CircuitState`, `TimeoutError`, `CircuitOpenError`.
|
|
140
|
+
- `validate` — `validatePatchDeep`, `ValidateDeepOptions`, `MAX_PATCH_DEPTH`,
|
|
141
|
+
`MAX_PATCH_KEYS`.
|
|
142
|
+
- `redaction` — `redactSecrets`, `REDACTED`.
|
|
143
|
+
- `atomic-write` — `atomicWriteFile`, `resolveStatePath`, `StatePathRef`,
|
|
144
|
+
`LockHandle`, `DEFAULT_LOCK_TTL_MS`.
|
|
145
|
+
- `clock` — `Clock`, `SystemClock`, `clone`.
|
|
146
|
+
- `migrations` — `migrate`, `VersionedState`, `CURRENT_STATE_VERSION`.
|
|
147
|
+
- `state-store` — `StateStore`, `MemoryStore`, `FileStore`.
|
|
148
|
+
- `events` — `RuntimeEventEmitter`, `runtimeEvents`, `RuntimeEventName`,
|
|
149
|
+
`RuntimeEventPayloads`, `RuntimeEventListener`.
|
|
150
|
+
- `logger` — `Logger`, `JsonLogger`, `JsonLoggerOptions`, `LogLevel`,
|
|
151
|
+
`LogFields`.
|
|
152
|
+
- `provider` — `LLMProvider`, `fromLLMFn`, `isLLMProvider`, `LLMUsage`,
|
|
153
|
+
`LLMResult`, `LLMCallOptions`, `LLMFnLike`.
|
|
154
|
+
- `config` — `defaultConfig`, `loadConfig`, `mergeConfig`, `SkillStateConfig`,
|
|
155
|
+
`CONFIG_FILE_NAME`.
|
|
156
|
+
- `shutdown` — `installShutdown`.
|
|
157
|
+
|
|
158
|
+
## Notes
|
|
159
|
+
|
|
160
|
+
- **Paper fidelity.** `formatPaper` reproduces the paper's Appendix A.4
|
|
161
|
+
template byte-verbatim (no schema description, no platform padding).
|
|
162
|
+
`getMetrics()` returns the §4.3 triad in raw string chars and nothing else:
|
|
163
|
+
`accuracy`, `averagePromptSize`, `totalTokens`.
|
|
164
|
+
- **O(1)/O(T).** The prompt is always `(P, Σₜ, Oₜ)` — no history is re-sent.
|
|
165
|
+
Reasoning **Rₜ** is returned but never stored (§3.2).
|
|
166
|
+
- **Zero dependencies.** `package.json` declares no runtime deps; Node >= 20.
|
|
167
|
+
- **`@non-paper`.** Everything under `instrumentation`/`resilience`/`validate`/
|
|
168
|
+
`redaction`/`atomic-write`/`clock`/`migrations`/`state-store`/`events`/
|
|
169
|
+
`logger`/`provider`/`config`/`shutdown` is additive and opt-in — it does
|
|
170
|
+
**not** appear in arXiv 2608.26263v3.
|
|
171
|
+
|
|
172
|
+
## Related
|
|
173
|
+
|
|
174
|
+
- Paper: [arXiv:2608.26263](https://arxiv.org/abs/2608.26263) (SKILL.state).
|
|
175
|
+
- Detailed design notes: [`state.md`](../../state.md).
|
|
176
|
+
- Reproducible measurements: [`BENCHMARK.md`](../../BENCHMARK.md).
|
|
177
|
+
- Platform adapters: `@skillstate/claude`, `@skillstate/opencode`,
|
|
178
|
+
`@skillstate/codex`, `@skillstate/mcp`; tools: `@skillstate/cli`,
|
|
179
|
+
`@skillstate/bench`.
|
|
180
|
+
|
|
181
|
+
## License
|
|
182
|
+
|
|
183
|
+
[MIT](LICENSE) © 2026 Vitaly Kuzyaev
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@skillstate/core",
|
|
3
|
-
"version": "2.0.
|
|
3
|
+
"version": "2.0.2",
|
|
4
4
|
"description": "Paper-exact skillstate runtime core (A.4 byte-verbatim formatPaper, §4.3 token tracker).",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -16,7 +16,9 @@
|
|
|
16
16
|
},
|
|
17
17
|
"./package.json": "./package.json"
|
|
18
18
|
},
|
|
19
|
-
"files": [
|
|
19
|
+
"files": [
|
|
20
|
+
"dist"
|
|
21
|
+
],
|
|
20
22
|
"sideEffects": false,
|
|
21
23
|
"engines": {
|
|
22
24
|
"node": ">=20"
|