SharedOS API v0.1.0-alpha.5

---

SharedOS API / @aicoo/sharedos-os

@aicoo/sharedos-os

Standard permission-controlled file tool adapters for SharedOS.

npm install @aicoo/sharedos-os@next

Hosts provide storage implementations; this package provides one canonical files namespace, portable argument schemas, canonical resource paths, exact per-call capability resolution, and tool definitions. Memory is represented by files under host-defined paths, not by a second storage namespace.

The standard handlers also use files as their logical tool namespace and sharedos as their catalog source. Hosts must explicitly include files in an effective namespace selection before those handlers can be discovered. Filesystem providers must still enforce root containment and reject symlink escapes.

SharedOS is currently an 0.x prerelease.

Interfaces

StandardOsProviders

Defined in: index.ts:210

Properties

Property	Modifier	Type	Defined in
<a id="property-files"></a> files?	readonly	ResourceProvider	index.ts:211
<a id="property-repo"></a> repo?	readonly	ResourceProvider	index.ts:212

Type Aliases

FilePath

FilePath = z.infer<typeof FilePathSchema>>

Defined in: index.ts:36

---

FilesAppendArguments

FilesAppendArguments = z.infer<typeof FilesAppendArgumentsSchema>>

Defined in: index.ts:105

---

FilesCreateArguments

FilesCreateArguments = z.infer<typeof FilesCreateArgumentsSchema>>

Defined in: index.ts:69

---

FilesDeleteArguments

FilesDeleteArguments = z.infer<typeof FilesDeleteArgumentsSchema>>

Defined in: index.ts:114

---

FilesGrepArguments

FilesGrepArguments = z.infer<typeof FilesGrepArgumentsSchema>>

Defined in: index.ts:60

---

FilesPathArguments

FilesPathArguments = z.infer<typeof FilesPathArgumentsSchema>>

Defined in: index.ts:39

---

FilesReplaceArguments

FilesReplaceArguments = z.infer<typeof FilesReplaceArgumentsSchema>>

Defined in: index.ts:95

---

FilesSearchArguments

FilesSearchArguments = z.infer<typeof FilesSearchArgumentsSchema>>

Defined in: index.ts:48

---

FilesSnapshotCreateArguments

FilesSnapshotCreateArguments = z.infer<typeof FilesSnapshotCreateArgumentsSchema>>

Defined in: index.ts:122

---

FilesSnapshotListArguments

FilesSnapshotListArguments = z.infer<typeof FilesSnapshotListArgumentsSchema>>

Defined in: index.ts:130

---

FilesSnapshotRestoreArguments

FilesSnapshotRestoreArguments = z.infer<typeof FilesSnapshotRestoreArgumentsSchema>>

Defined in: index.ts:139

---

RepoCommitArguments

RepoCommitArguments = z.infer<typeof RepoCommitArgumentsSchema>>

Defined in: index.ts:198

---

RepoDiffArguments

RepoDiffArguments = z.infer<typeof RepoDiffArgumentsSchema>>

Defined in: index.ts:180

---

RepoLogArguments

RepoLogArguments = z.infer<typeof RepoLogArgumentsSchema>>

Defined in: index.ts:188

---

RepoPathspec

RepoPathspec = z.infer<typeof RepoPathspecSchema>>

Defined in: index.ts:152

---

RepoStageArguments

RepoStageArguments = z.infer<typeof RepoStageArgumentsSchema>>

Defined in: index.ts:193

---

RepoStatusArguments

RepoStatusArguments = z.infer<typeof RepoStatusArgumentsSchema>>

Defined in: index.ts:171

Variables

FilePathSchema

const FilePathSchema: ZodArray<ZodString, "many">>

Defined in: index.ts:35

---

FILES_NAMESPACE

const FILES_NAMESPACE: "files" = "files"

Defined in: index.ts:19

The canonical SharedOS resource plane. Memory is a role of files, not a second store.

---

FilesAppendArgumentsSchema

const FilesAppendArgumentsSchema: ZodObject<{ content: ZodType<JsonValue, ZodTypeDef, JsonValue>>; expectedVersion: ZodOptional<ZodEffects<ZodEffects<ZodString, string, string>>, string, string>>>>; metadata: ZodOptional<ZodRecord<ZodString, ZodType<JsonValue, ZodTypeDef, JsonValue>>>>>>; path: ZodArray<ZodString, "many">>; }, "strict", ZodTypeAny, { content: JsonValue; expectedVersion?: string; metadata?: Record<string, JsonValue>>; path: string[]; }, { content: JsonValue; expectedVersion?: string; metadata?: Record<string, JsonValue>>; path: string[]; }>

Defined in: index.ts:97

---

FilesCreateArgumentsSchema

const FilesCreateArgumentsSchema: ZodObject<{ content: ZodType<JsonValue, ZodTypeDef, JsonValue>>; metadata: ZodOptional<ZodRecord<ZodString, ZodType<JsonValue, ZodTypeDef, JsonValue>>>>>>; path: ZodArray<ZodString, "many">>; }, "strict", ZodTypeAny, { content: JsonValue; metadata?: Record<string, JsonValue>>; path: string[]; }, { content: JsonValue; metadata?: Record<string, JsonValue>>; path: string[]; }>

Defined in: index.ts:62

---

FilesDeleteArgumentsSchema

const FilesDeleteArgumentsSchema: ZodObject<{ expectedVersion: ZodOptional<ZodEffects<ZodEffects<ZodString, string, string>>, string, string>>>>; path: ZodArray<ZodString, "many">>; recursive: ZodDefault<ZodBoolean>>; }, "strict", ZodTypeAny, { expectedVersion?: string; path: string[]; recursive: boolean; }, { expectedVersion?: string; path: string[]; recursive?: boolean; }>

Defined in: index.ts:107

---

FilesGrepArgumentsSchema

const FilesGrepArgumentsSchema: ZodObject<{ caseSensitive: ZodDefault<ZodBoolean>>; contextAfter: ZodDefault<ZodNumber>>; contextBefore: ZodDefault<ZodNumber>>; mode: ZodDefault<ZodEnum<["literal", "regex"]>>; path: ZodArray<ZodString, "many">>; pattern: ZodString; }, "strict", ZodTypeAny, { caseSensitive: boolean; contextAfter: number; contextBefore: number; mode: "literal" | "regex"; path: string[]; pattern: string; }, { caseSensitive?: boolean; contextAfter?: number; contextBefore?: number; mode?: "literal" | "regex"; path: string[]; pattern: string; }>

Defined in: index.ts:50

---

FilesPathArgumentsSchema

const FilesPathArgumentsSchema: ZodObject<{ path: ZodArray<ZodString, "many">>; }, "strict", ZodTypeAny, { path: string[]; }, { path: string[]; }>

Defined in: index.ts:38

---

FilesReplaceArgumentsSchema

const FilesReplaceArgumentsSchema: ZodObject<{ content: ZodType<JsonValue, ZodTypeDef, JsonValue>>; expectedVersion: ZodOptional<ZodEffects<ZodEffects<ZodString, string, string>>, string, string>>>>; path: ZodArray<ZodString, "many">>; }, "strict", ZodTypeAny, { content: JsonValue; expectedVersion?: string; path: string[]; }, { content: JsonValue; expectedVersion?: string; path: string[]; }>

Defined in: index.ts:88

---

FilesSearchArgumentsSchema

const FilesSearchArgumentsSchema: ZodObject<{ limit: ZodOptional<ZodNumber>>; path: ZodArray<ZodString, "many">>; query: ZodString; }, "strict", ZodTypeAny, { limit?: number; path: string[]; query: string; }, { limit?: number; path: string[]; query: string; }>

Defined in: index.ts:41

---

FilesSnapshotCreateArgumentsSchema

const FilesSnapshotCreateArgumentsSchema: ZodObject<{ label: ZodOptional<ZodString>>; path: ZodArray<ZodString, "many">>; }, "strict", ZodTypeAny, { label?: string; path: string[]; }, { label?: string; path: string[]; }>

Defined in: index.ts:116

---

FilesSnapshotListArgumentsSchema

const FilesSnapshotListArgumentsSchema: ZodObject<{ limit: ZodOptional<ZodNumber>>; path: ZodArray<ZodString, "many">>; }, "strict", ZodTypeAny, { limit?: number; path: string[]; }, { limit?: number; path: string[]; }>

Defined in: index.ts:124

---

FilesSnapshotRestoreArgumentsSchema

const FilesSnapshotRestoreArgumentsSchema: ZodObject<{ expectedVersion: ZodOptional<ZodEffects<ZodEffects<ZodString, string, string>>, string, string>>>>; path: ZodArray<ZodString, "many">>; snapshotId: ZodString; }, "strict", ZodTypeAny, { expectedVersion?: string; path: string[]; snapshotId: string; }, { expectedVersion?: string; path: string[]; snapshotId: string; }>

Defined in: index.ts:132

---

REPO_NAMESPACE

const REPO_NAMESPACE: "repo" = "repo"

Defined in: index.ts:32

The Git resource plane.

repo and FILES_NAMESPACE may address the same directory and share no authority: capabilityMatches compares resource.namespace before it looks at anything else, so a file grant over a working tree matches nothing here and a repository grant matches nothing there. Modelling commit as a write under files would have made every holder of file-write authority a committer, which is the permission cross-product ADR 0005 refuses. See ADR 0024.

---

RepoCommitArgumentsSchema

const RepoCommitArgumentsSchema: ZodObject<{ message: ZodEffects<ZodString, string, string>>; path: ZodArray<ZodString, "many">>; }, "strict", ZodTypeAny, { message: string; path: string[]; }, { message: string; path: string[]; }>

Defined in: index.ts:195

---

RepoDiffArgumentsSchema

const RepoDiffArgumentsSchema: ZodObject<{ path: ZodArray<ZodString, "many">>; pathspec: ZodOptional<ZodArray<ZodArray<ZodString, "many">>, "many">>>>; staged: ZodDefault<ZodBoolean>>; }, "strict", ZodTypeAny, { path: string[]; pathspec?: string[][]; staged: boolean; }, { path: string[]; pathspec?: string[][]; staged?: boolean; }>

Defined in: index.ts:173

---

RepoLogArgumentsSchema

const RepoLogArgumentsSchema: ZodObject<{ maxCount: ZodOptional<ZodNumber>>; path: ZodArray<ZodString, "many">>; }, "strict", ZodTypeAny, { maxCount?: number; path: string[]; }, { maxCount?: number; path: string[]; }>

Defined in: index.ts:182

---

RepoPathspecSchema

const RepoPathspecSchema: ZodArray<ZodArray<ZodString, "many">>, "many">>

Defined in: index.ts:151

Paths inside a repository, selecting what a diff or a stage covers.

Provider input, not a second resource: staging is authorized at the repository, and the provider confines every entry beneath it exactly as validatePathArguments does today. They are carried in the same canonical segment vocabulary as any other path (ADR 0004), so a traversal marker is refused before the provider is reached -- a vocabulary constraint, not the authorization boundary. See ADR 0024.

---

RepoStageArgumentsSchema

const RepoStageArgumentsSchema: ZodObject<{ path: ZodArray<ZodString, "many">>; pathspec: ZodArray<ZodArray<ZodString, "many">>, "many">>; }, "strict", ZodTypeAny, { path: string[]; pathspec: string[][]; }, { path: string[]; pathspec: string[][]; }>

Defined in: index.ts:190

---

RepoStatusArgumentsSchema

const RepoStatusArgumentsSchema: ZodObject<{ path: ZodArray<ZodString, "many">>; }, "strict", ZodTypeAny, { path: string[]; }, { path: string[]; }>

Defined in: index.ts:170

---

SHAREDOS_TOOL_SOURCE

const SHAREDOS_TOOL_SOURCE: "sharedos" = "sharedos"

Defined in: index.ts:33

Functions

createFileTools()

createFileTools(provider): readonly ToolHandler[]

Defined in: index.ts:238

Portable file tools over one host-owned provider.

A host may expose roots such as Raw, Memory, Workspace, and Wiki, but they remain paths in this one resource plane. Search indexes and context mounts must preserve the same file grants; they are not independent authority.

Parameters

Parameter	Type
provider	ResourceProvider

Returns

readonly ToolHandler[]

---

createRepoTools()

createRepoTools(provider): readonly ToolHandler[]

Defined in: index.ts:472

The vetted Git subset over one host-owned provider, beside the file tools.

Five tools, one per subcommand the host's safe-git allows, each resolving to an action of its own: a plane with a single write could not express "may stage, never commit", which is the distinction hosts already make. push, reset, checkout, clean, config, and remote are deliberately absent and stay behind whatever authorizes an arbitrary shell command.

The capability names the repository; the provider confines every path argument beneath it. SharedOS ships the vocabulary and the authorization and never a Git implementation, so the execution hardening the host applies -- disabled hooks, no system or global config, no external diff or textconv drivers, no clean filters, refused symlinks -- holds because the provider is the only code that can turn a capability into an invocation, not because any grant asked for it. See ADR 0024.

Parameters

Parameter	Type
provider	ResourceProvider

Returns

readonly ToolHandler[]

---

registerStandardOsTools()

registerStandardOsTools(kernel, providers): void

Defined in: index.ts:215

Parameters

Parameter	Type
kernel	Pick<SharedOSKernel, "registerTool">
providers	StandardOsProviders

Returns

void