@cleanslate/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 CleanSlate
+Copyright (c) 2015 - present Microsoft Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,48 @@
+CleanSlate
+Copyright (c) 2026 CleanSlate
+
+This product includes software developed by third parties, listed below.
+CleanSlate itself is distributed under the MIT License; see LICENSE.
+
+--------------------------------------------------------------------------------
+
+Visual Studio Code
+Copyright (c) 2015 - present Microsoft Corporation
+Licensed under the MIT License.
+https://github.com/microsoft/vscode
+
+CleanSlate is a fork of Visual Studio Code. The full license text is retained
+in vscode-fork/LICENSE.txt. CleanSlate is not affiliated with, endorsed by, or
+sponsored by Microsoft.
+
+@cleanslate/sdk additionally vendors a set of base modules from Visual Studio Code
+into packages/cleanslate-sdk/src/core/, so that the runtime can be consumed without
+an editor build. Each vendored file retains its original Microsoft copyright
+header and names its source path. The full list, the modules that were
+reimplemented instead of copied, and the reasons, are in
+packages/cleanslate-sdk/VENDOR.md.
+
+--------------------------------------------------------------------------------
+
+opencode
+Copyright (c) opencode contributors
+Licensed under the MIT License.
+https://github.com/anomalyco/opencode
+
+Portions of the following files are derived from opencode:
+
+  packages/cleanslate-sdk/src/protocol/cleanSlateModelCapabilities.ts
+      - the OpenAI reasoning-effort tier tables and their version gates
+
+    (this file moved out of the fork into @cleanslate/sdk; it was previously at
+     vscode-fork/src/vs/workbench/services/cleanSlate/common/core/)
+
+--------------------------------------------------------------------------------
+
+Xenova/bge-small-en-v1.5
+Licensed under the MIT License.
+https://huggingface.co/Xenova/bge-small-en-v1.5
+
+The quantized ONNX model bundled at
+vscode-fork/resources/cleanslate/models/Xenova/bge-small-en-v1.5/ is used for
+on-device code embeddings.

package/README.md

@@ -0,0 +1,103 @@
+# @cleanslate/sdk
+
+The Slate agent runtime: execution loop, tool protocol, edit engine and Node
+host. It is the engine behind [CleanSlate](https://github.com/TheWariend/CleanSlate)
+— the same code drives the editor and the terminal.
+
+It has no editor dependency. A surface supplies host capabilities; the runtime
+drives the loop.
+
+> **Status: 0.x.** The host interfaces are still settling. Expect breaking
+> changes between minor versions.
+
+## Install
+
+```bash
+npm install @cleanslate/sdk
+```
+
+Node 20 or later.
+
+## What is in it
+
+- **The execution loop** — turn management, budgets, an evidence ledger, and the
+  completion boundary that decides when a task is actually finished.
+- **59 tools**, listed below.
+- **The edit engine** — exact-string matching with anchors, version guards and
+  atomic multi-file application.
+- **A Node host** — filesystem-backed text models and child-process commands, so
+  the runtime works with no editor present.
+
+## The tools
+
+`ALL_TOOLS` exports 59 tools. Availability depends on what the host provides —
+a surface with no browser has no browser tools.
+
+| Group | Count | Tools |
+| --- | --- | --- |
+| Discovery | 12 | `read_file`, `read_file_range`, `semantic_search`, `search_workspace`, `search_codebase`, `find_by_name`, `grep_search`, `web_search`, `web_fetch`, `list_dir`, `read_lints`, `find_references` |
+| Browser | 26 | `browser_open`, `browser_snapshot`, `browser_click`, `browser_fill`, `browser_type`, `browser_key`, `browser_scroll`, `browser_screenshot`, `browser_diagnostics`, tab and annotation control, … |
+| System | 8 | `spawn_worker`, `list_skills`, `mcp_list_tools`, `mcp_call_tool`, `read_reference`, `update_todo`, `ask_question`, `submit_artifact` |
+| Edit | 4 | `apply_edit`, `multi_file_replace`, `write_file`, `file_history_rewind` |
+| Execution | 4 | `execute_command`, `start_background_command`, `read_background_command`, `stop_background_command` |
+| Symbols | 3 | `read_symbols`, `get_definitions`, `undo_edit` |
+| Context | 1 | `get_open_files` |
+| Creation | 1 | `create_multiple_files` |
+
+```js
+import { ALL_TOOLS, getToolByName } from '@cleanslate/sdk';
+
+ALL_TOOLS.length;                  // 59
+getToolByName('multi_file_replace');
+```
+
+Every command-running tool passes through the host's approval gate first, which
+refuses by default.
+
+## Shape
+
+```js
+import { createNodeHost, ALL_TOOLS } from '@cleanslate/sdk';
+
+const context = createNodeHost({
+  rootPath: process.cwd(),
+  configuration: { /* provider settings */ },
+  // Defaults to refusing every command, so a host that forgets a policy
+  // fails safe rather than running whatever the model asks for.
+  approveCommand: async ({ command }) => confirm(command)
+});
+```
+
+A host implements as much as it can and leaves the rest undefined. Tools that
+need an absent capability report it as unavailable instead of failing the run —
+so a terminal without a browser view simply has no browser tools.
+
+## Host capabilities
+
+| Interface | Provides |
+| --- | --- |
+| `ISlateTextModel` / `IModelHost` | reading and replacing text |
+| `IFileHost` | the filesystem |
+| `IWorkspaceHost` | workspace roots |
+| `ISearchHost` | text search |
+| `IMarkerHost` | diagnostics |
+| `ILanguageFeaturesHost` | definitions, references, symbols |
+| `ITreeSitterHost` | grammars for structural queries |
+| `ICleanSlateBulkEditHost` | applying edits as one unit |
+| `ICleanSlateBrowserAutomationService` | a browser, if the surface has one |
+
+`ISlateTextModel` is deliberately small — about fifteen members, all concerned
+with reading and replacing text — so a host can back a document with a file
+rather than an editor.
+
+## Vendored code
+
+`src/core/` contains modules copied from
+[microsoft/vscode](https://github.com/microsoft/vscode) (MIT), with their
+copyright headers intact. Four more were reimplemented rather than copied, to
+avoid pulling a large subtree in for a handful of functions. What was copied,
+what was rewritten, and why, is recorded in [VENDOR.md](./VENDOR.md).
+
+## Licence
+
+MIT. See [LICENSE](./LICENSE) and [NOTICE](./NOTICE).

package/VENDOR.md

@@ -0,0 +1,60 @@
+# Vendored code
+
+`src/core/` contains modules taken from [microsoft/vscode](https://github.com/microsoft/vscode)
+(MIT). They are copied rather than depended on: the fork's `vs/` tree is not a
+published package, and importing it would tie the runtime to an editor build.
+
+## Copied as-is
+
+Each carries its original Microsoft copyright header plus a note naming its
+source path. The only mechanical change is `export const enum` →`export enum`,
+because `const enum` cannot cross a module boundary under `isolatedModules`.
+
+| SDK path | Source |
+| --- | --- |
+| `core/uri.ts` | `vs/base/common/uri.ts` |
+| `core/charCode.ts` | `vs/base/common/charCode.ts` |
+| `core/marshallingIds.ts` | `vs/base/common/marshallingIds.ts` |
+| `core/event.ts` | `vs/base/common/event.ts` |
+| `core/lifecycle.ts` | `vs/base/common/lifecycle.ts` |
+| `core/cancellation.ts` | `vs/base/common/cancellation.ts` |
+| `core/errors.ts` | `vs/base/common/errors.ts` |
+| `core/functional.ts` | `vs/base/common/functional.ts` |
+| `core/iterator.ts` | `vs/base/common/iterator.ts` |
+| `core/linkedList.ts` | `vs/base/common/linkedList.ts` |
+| `core/stopwatch.ts` | `vs/base/common/stopwatch.ts` |
+| `core/collections.ts` | `vs/base/common/collections.ts` |
+| `core/arrays.ts` | `vs/base/common/arrays.ts` |
+| `core/arraysFind.ts` | `vs/base/common/arraysFind.ts` |
+| `core/map.ts` | `vs/base/common/map.ts` |
+| `core/types.ts` | `vs/base/common/types.ts` |
+| `core/assert.ts` | `vs/base/common/assert.ts` |
+| `core/position.ts` | `vs/editor/common/core/position.ts` |
+| `core/range.ts` | `vs/editor/common/core/range.ts` |
+| `core/diff/diff.ts` | `vs/base/common/diff/diff.ts` |
+| `core/diff/diffChange.ts` | `vs/base/common/diff/diffChange.ts` |
+
+`uri.ts` has one further change: `import * as paths from './path.js'` becomes
+`import * as paths from 'node:path'`. It uses only `win32.join` and
+`posix.join`, which Node provides with the same semantics.
+
+## Reimplemented instead of copied
+
+Four modules were rewritten. Each was a cut edge that would otherwise have
+pulled a large subtree in for a handful of functions — following those edges
+verbatim would have meant 32 files and ~16,200 lines instead of the 21 above.
+
+| SDK path | Replaces | Why |
+| --- | --- | --- |
+| `core/platform.ts` | `vs/base/common/platform.ts` | The original resolves the UI locale, which is the sole reason it imports `vs/nls`. The runtime needs only the OS booleans. |
+| `core/resources.ts` | `vs/base/common/resources.ts` | Six functions (`basename`, `dirname`, `joinPath`, `normalizePath`, `relativePath`, `isEqualOrParent`) were reaching `extpath` → `network` → `strings` → `nls`. Rewritten on `node:path`, preserving the original semantics; see the file header for the two deliberate simplifications. |
+| `core/hash.ts` | `vs/base/common/hash.ts` | Only `stringHash` is used. The original also carries SHA-1 and structural hashing, pulling in `buffer` and `strings`. The algorithm is reproduced exactly, because diff output is keyed on it. |
+| `core/buffer.ts` | `vs/base/common/buffer.ts` | Five members are used. The original carries streaming and browser fallbacks via `stream` and `lazy`; Node's `Buffer` covers what is needed. |
+
+Nothing from `vs/nls` is present, directly or transitively.
+
+## Refreshing
+
+`scripts/vendor.mjs` regenerates the copied files. Re-run it after rebasing the
+fork on a newer VS Code, then re-run the SDK tests — `core/resources.ts` and
+`core/hash.ts` are hand-written and will not be updated by it.

package/dist/agent/cleanSlateAgentExecutionPhase.d.ts

@@ -0,0 +1,55 @@
+import { URI } from '../core/uri.js';
+import { AgentPhase } from './cleanSlatePrompts.js';
+import { CleanSlateExecutionEvidenceLedger } from './cleanSlateExecutionEvidenceLedger.js';
+import type { IExecutionRunnerOptions } from './cleanSlateQueryRunner.js';
+export interface IFailedEditOperation {
+    toolName: string;
+    path?: string;
+    code?: string;
+    message?: string;
+    recoveryHint?: string;
+    currentVersionId?: number;
+    attemptedEdits?: number;
+    allMatches?: Array<{
+        lineNumber: number;
+        endLineNumber: number;
+        lineContent: string;
+        confidence: number;
+    }>;
+}
+export interface IExecutionEditFailureState {
+    count: number;
+    lastCode?: string;
+    path?: string;
+}
+export declare class CleanSlateAgentExecutionPhase {
+    private readonly options;
+    constructor(options: IExecutionRunnerOptions);
+    validateToolCallForPhase(phase: AgentPhase, toolName: string, input: any): string | undefined;
+    primeExecutionEvidenceLedgerForPlannedToolCall(evidenceLedger: CleanSlateExecutionEvidenceLedger, phase: AgentPhase, toolName: string, input: any): void;
+    updateExecutionEvidenceLedgerFromToolResult(evidenceLedger: CleanSlateExecutionEvidenceLedger, toolName: string, input: any, result: any): void;
+    registerPostMutationEvidence(evidenceLedger: CleanSlateExecutionEvidenceLedger, toolName: string, input: any): void;
+    extractMutationTargetPaths(toolName: string, input: any): string[];
+    extractLocatorScopesFromToolCallInput(toolName: string, input: any): string[];
+    extractLocatedPathsFromToolCallInput(toolName: string, input: any): string[];
+    extractLocatedPathsFromToolResult(toolName: string, input: any, result: any): string[];
+    extractReadPathsFromToolCallAndResult(toolName: string, input: any, result: any): string[];
+    extractSymbolEvidenceFromToolInput(toolName: string, input: any): string[];
+    extractSymbolEvidenceFromToolResult(toolName: string, input: any, result: any): string[];
+    collectSymbolNames(symbols: any): string[];
+    toEvidencePathKey(pathCandidate: unknown): string | undefined;
+    resolveEvidenceCandidateToUri(pathCandidate: unknown): URI | undefined;
+    getCurrentModelVersionForPathCandidate(pathCandidate: unknown): number | undefined;
+    isExecutionLocatorTool(toolName: string): boolean;
+    isExecutionReadTool(toolName: string): boolean;
+    getStructuredEditFailureKey(toolName: string, input: any): string;
+    collectFailedEditOperations(toolName: string, toolResult: any): IFailedEditOperation[];
+    buildEditRecoveryPrompt(failures: IFailedEditOperation[], repeatedFailures?: IExecutionEditFailureState[]): string;
+    buildUnknownToolRecoveryPrompt(requestedToolName: string, toolResult: any): string;
+    hasMaterializedBootstrapWorkspace(): Promise<boolean>;
+    isIgnorableWorkspaceEntry(name: string): boolean;
+    isImplementationPlanPath(pathCandidate: unknown): boolean;
+    isAnalysisPath(pathCandidate: unknown): boolean;
+    isVirtualArtifactPath(pathCandidate: unknown): boolean;
+}
+//# sourceMappingURL=cleanSlateAgentExecutionPhase.d.ts.map

package/dist/agent/cleanSlateAgentExecutionPhase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cleanSlateAgentExecutionPhase.d.ts","sourceRoot":"","sources":["../../src/agent/cleanSlateAgentExecutionPhase.ts"],"names":[],"mappings":"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"}