@agentproto/storage 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 agentproto contributors
+
+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/README.md

@@ -0,0 +1,23 @@
+# @agentproto/storage
+
+AIP-35 `STORAGE.md` reference implementation. A composable schema block defining the `storage` field — provider, config, sync semantics, auth ref, exclude rules — for any manifest that names a backing store. Reused by WORKSPACE.md (AIP-34) and any future manifest that names persistent state. Inline or ref, mirroring AIP-17 RUNNER and AIP-19 SECRETS.
+
+> **Status: 0.1.0-alpha.** Generated by `scripts/scaffold-aip.mjs` — `build()` and `validate()` bodies are TODOs.
+
+Spec: <https://agentproto.sh/docs/aip-35>
+
+## Usage
+
+```ts
+import { defineStorage } from "@agentproto/storage"
+
+const x = defineStorage({
+  id: "my-storage",
+  description: "Short purpose.",
+  // ...
+})
+```
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

package/dist/chunk-JMBOQNBX.mjs

@@ -0,0 +1,48 @@
+import { z } from 'zod';
+import { createDoctype } from '@agentproto/define-doctype';
+
+/**
+ * @agentproto/storage v0.1.0-alpha
+ * AIP-35 STORAGE.md `defineStorage` reference implementation.
+ */
+
+var storageFrontmatterSchema = z.object({ "schema": z.literal("storage/v1").describe("Standalone-only. Identifies the doctype + version. Absent when the block is inlined in another manifest.").optional(), "id": z.string().regex(new RegExp("^@[a-z0-9][a-z0-9-]*/[a-z0-9][a-z0-9-]*$")).describe("Standalone-only. Globally addressable id `@<owner-slug>/<storage-slug>`.").optional(), "version": z.string().regex(new RegExp("^\\d+\\.\\d+\\.\\d+(?:[-+][\\w.\\-]+)?$")).describe("Standalone-only. Spec version of THIS file. Bump on breaking shape change.").optional(), "provider": z.string().min(1).describe("Backend kind. Day-1 enumerated set: cloud-bucket | self-bucket | github | local-fs | dev-local | mastra-s3 | mastra-azure. Hosts MAY register additional ids; the schema accepts any non-empty string and host-side validation narrows."), "config": z.record(z.string(), z.any()).describe("Provider-specific connection fields. Shape varies per provider (see AIP-35 \xA7Provider config shapes)."), "sync": z.any().describe("Sync semantics. Lifecycle triggers reference AIP-37 event names.").optional(), "auth": z.any().describe("Reference to AIP-19 SECRETS.md (or future ENV.md) for credentials.").optional(), "identity": z.any().describe("AIP-23 identity-ref block \u2014 commit author(s) for syncing providers (github). Supports multi-attribution (primary + co-authors).").optional(), "exclude": z.array(z.string()).describe("Paths NOT mirrored to the backing store. Glob-ish, prefix-matched.").default([]), "read_only": z.boolean().describe("Reject writes at the storage layer.").default(false), "metadata": z.record(z.string(), z.any()).describe("Free-form, namespaced. Authors MAY stash adapter-specific hints under namespaced keys.").optional() }).strict().describe("Validates the YAML frontmatter portion of an AIP-35 STORAGE.md manifest, OR the inline form embedded in any other manifest's `storage:` block. Filesystem-only \u2014 sandbox-shaped backends (e2b/modal/...) live in AIP-36 SANDBOX.md.");
+var defineStorageInner = createDoctype({
+  aip: 35,
+  name: "storage",
+  readDescription: false,
+  // AIP-35 makes `id` standalone-only — inline storage blocks (every
+  // host registration we care about) carry only `provider` + `config`.
+  // Fall back to `provider` for the cross-AIP id-pattern check; the
+  // resolution order mirrors AIP-43 § Identity (id → provider → slug).
+  readIdentity: (def) => {
+    if (typeof def.id === "string" && def.id.length > 0) return def.id;
+    return def.provider;
+  },
+  validate(def) {
+    const { factory: _factory, capabilities: _capabilities, ...manifest } = def;
+    const result = storageFrontmatterSchema.safeParse(manifest);
+    if (!result.success) {
+      throw new Error(
+        `defineStorage (AIP-35): ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+      );
+    }
+  },
+  build(def) {
+    const { factory, capabilities, ...manifest } = def;
+    return {
+      ...manifest,
+      ...factory !== void 0 ? { factory } : {},
+      ...capabilities !== void 0 ? { capabilities: Object.freeze({ ...capabilities }) } : {}
+    };
+  }
+});
+function defineStorage(definition) {
+  return defineStorageInner(
+    definition
+  );
+}
+
+export { defineStorage, storageFrontmatterSchema };
+//# sourceMappingURL=chunk-JMBOQNBX.mjs.map
+//# sourceMappingURL=chunk-JMBOQNBX.mjs.map

package/dist/chunk-JMBOQNBX.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/schema.ts","../src/define-storage.ts"],"names":[],"mappings":";;;;;;;;AAeO,IAAM,wBAAA,GAA2B,CAAA,CAAE,MAAA,CAAO,EAAE,QAAA,EAAU,CAAA,CAAE,OAAA,CAAQ,YAAY,CAAA,CAAE,QAAA,CAAS,0GAA0G,CAAA,CAAE,UAAS,EAAG,IAAA,EAAM,CAAA,CAAE,MAAA,EAAO,CAAE,KAAA,CAAM,IAAI,MAAA,CAAO,0CAA0C,CAAC,CAAA,CAAE,QAAA,CAAS,0EAA0E,CAAA,CAAE,QAAA,EAAS,EAAG,SAAA,EAAW,EAAE,MAAA,EAAO,CAAE,KAAA,CAAM,IAAI,MAAA,CAAO,yCAAyC,CAAC,CAAA,CAAE,SAAS,4EAA4E,CAAA,CAAE,QAAA,EAAS,EAAG,UAAA,EAAY,CAAA,CAAE,MAAA,EAAO,CAAE,IAAI,CAAC,CAAA,CAAE,QAAA,CAAS,yOAAyO,CAAA,EAAG,QAAA,EAAU,CAAA,CAAE,MAAA,CAAO,EAAE,MAAA,EAAO,EAAG,CAAA,CAAE,GAAA,EAAK,CAAA,CAAE,QAAA,CAAS,yGAAsG,GAAG,MAAA,EAAQ,CAAA,CAAE,GAAA,EAAI,CAAE,QAAA,CAAS,kEAAkE,CAAA,CAAE,QAAA,EAAS,EAAG,MAAA,EAAQ,CAAA,CAAE,GAAA,EAAI,CAAE,QAAA,CAAS,oEAAoE,CAAA,CAAE,UAAS,EAAG,UAAA,EAAY,CAAA,CAAE,GAAA,EAAI,CAAE,QAAA,CAAS,sIAAiI,CAAA,CAAE,UAAS,EAAG,SAAA,EAAW,CAAA,CAAE,KAAA,CAAM,CAAA,CAAE,MAAA,EAAQ,CAAA,CAAE,SAAS,oEAAoE,CAAA,CAAE,OAAA,CAAQ,EAAW,CAAA,EAAG,WAAA,EAAa,CAAA,CAAE,SAAQ,CAAE,QAAA,CAAS,qCAAqC,CAAA,CAAE,OAAA,CAAQ,KAAK,CAAA,EAAG,UAAA,EAAY,EAAE,MAAA,CAAO,CAAA,CAAE,MAAA,EAAO,EAAG,CAAA,CAAE,GAAA,EAAK,CAAA,CAAE,SAAS,wFAAwF,CAAA,CAAE,QAAA,EAAS,EAAG,CAAA,CAAE,MAAA,EAAO,CAAE,SAAS,0OAAqO;ACgBx9D,IAAM,qBAAqB,aAAA,CAGzB;AAAA,EACA,GAAA,EAAK,EAAA;AAAA,EACL,IAAA,EAAM,SAAA;AAAA,EACN,eAAA,EAAiB,KAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAKjB,cAAc,CAAA,GAAA,KAAO;AACnB,IAAA,IAAI,OAAO,IAAI,EAAA,KAAO,QAAA,IAAY,IAAI,EAAA,CAAG,MAAA,GAAS,CAAA,EAAG,OAAO,GAAA,CAAI,EAAA;AAChE,IAAA,OAAO,GAAA,CAAI,QAAA;AAAA,EACb,CAAA;AAAA,EACA,SAAS,GAAA,EAAK;AAKZ,IAAA,MAAM,EAAE,OAAA,EAAS,QAAA,EAAU,cAAc,aAAA,EAAe,GAAG,UAAS,GAAI,GAAA;AACxE,IAAA,MAAM,MAAA,GAAS,wBAAA,CAAyB,SAAA,CAAU,QAAQ,CAAA;AAC1D,IAAA,IAAI,CAAC,OAAO,OAAA,EAAS;AACnB,MAAA,MAAM,IAAI,KAAA;AAAA,QACR,2BAA2B,MAAA,CAAO,KAAA,CAAM,OACrC,GAAA,CAAI,CAAA,CAAA,KAAK,GAAG,CAAA,CAAE,IAAA,CAAK,KAAK,GAAG,CAAC,KAAK,CAAA,CAAE,OAAO,EAAE,CAAA,CAC5C,IAAA,CAAK,IAAI,CAAC,CAAA;AAAA,OACf;AAAA,IACF;AAAA,EAIF,CAAA;AAAA,EACA,MAAM,GAAA,EAAK;AAIT,IAAA,MAAM,EAAE,OAAA,EAAS,YAAA,EAAc,GAAG,UAAS,GAAI,GAAA;AAC/C,IAAA,OAAO;AAAA,MACL,GAAG,QAAA;AAAA,MACH,GAAI,OAAA,KAAY,MAAA,GAAY,EAAE,OAAA,KAAY,EAAC;AAAA,MAC3C,GAAI,YAAA,KAAiB,MAAA,GACjB,EAAE,YAAA,EAAc,MAAA,CAAO,MAAA,CAAO,EAAE,GAAG,YAAA,EAAc,CAAA,KACjD;AAAC,KACP;AAAA,EACF;AACF,CAAC,CAAA;AAOM,SAAS,cAId,UAAA,EAC+C;AAC/C,EAAA,OAAO,kBAAA;AAAA,IACL;AAAA,GACF;AACF","file":"chunk-JMBOQNBX.mjs","sourcesContent":["/**\n * AIP-35 STORAGE.md frontmatter zod schema.\n *\n * Generated from `resources/aip-35/draft/STORAGE.schema.json` via\n * json-schema-to-zod. Imported by both `define-storage.ts` (TS path\n * validation) and `manifest/index.ts` (.md path validation) so every\n * field-level constraint runs in both authoring paths from a single\n * source of truth — re-run scaffold-aip to refresh after spec changes.\n *\n * Cross-field rules (if/then/allOf in JSON Schema) don't translate\n * cleanly and live in `define-storage.ts`'s `validate(def)` instead.\n */\n\nimport { z } from \"zod\"\n\nexport const storageFrontmatterSchema = z.object({ \"schema\": z.literal(\"storage/v1\").describe(\"Standalone-only. Identifies the doctype + version. Absent when the block is inlined in another manifest.\").optional(), \"id\": z.string().regex(new RegExp(\"^@[a-z0-9][a-z0-9-]*/[a-z0-9][a-z0-9-]*$\")).describe(\"Standalone-only. Globally addressable id `@<owner-slug>/<storage-slug>`.\").optional(), \"version\": z.string().regex(new RegExp(\"^\\\\d+\\\\.\\\\d+\\\\.\\\\d+(?:[-+][\\\\w.\\\\-]+)?$\")).describe(\"Standalone-only. Spec version of THIS file. Bump on breaking shape change.\").optional(), \"provider\": z.string().min(1).describe(\"Backend kind. Day-1 enumerated set: cloud-bucket | self-bucket | github | local-fs | dev-local | mastra-s3 | mastra-azure. Hosts MAY register additional ids; the schema accepts any non-empty string and host-side validation narrows.\"), \"config\": z.record(z.string(), z.any()).describe(\"Provider-specific connection fields. Shape varies per provider (see AIP-35 §Provider config shapes).\"), \"sync\": z.any().describe(\"Sync semantics. Lifecycle triggers reference AIP-37 event names.\").optional(), \"auth\": z.any().describe(\"Reference to AIP-19 SECRETS.md (or future ENV.md) for credentials.\").optional(), \"identity\": z.any().describe(\"AIP-23 identity-ref block — commit author(s) for syncing providers (github). Supports multi-attribution (primary + co-authors).\").optional(), \"exclude\": z.array(z.string()).describe(\"Paths NOT mirrored to the backing store. Glob-ish, prefix-matched.\").default([] as never), \"read_only\": z.boolean().describe(\"Reject writes at the storage layer.\").default(false), \"metadata\": z.record(z.string(), z.any()).describe(\"Free-form, namespaced. Authors MAY stash adapter-specific hints under namespaced keys.\").optional() }).strict().describe(\"Validates the YAML frontmatter portion of an AIP-35 STORAGE.md manifest, OR the inline form embedded in any other manifest's `storage:` block. Filesystem-only — sandbox-shaped backends (e2b/modal/...) live in AIP-36 SANDBOX.md.\")\n\nexport type StorageFrontmatter = z.infer<typeof storageFrontmatterSchema>\n","import { createDoctype } from \"@agentproto/define-doctype\"\nimport { storageFrontmatterSchema } from \"./schema.js\"\nimport type {\n  StorageRuntimeHandle,\n  StorageRuntimeInput,\n} from \"./types.js\"\n\n/**\n * AIP-35 reference implementation of `defineStorage`.\n *\n * Built on `createDoctype` so the cross-AIP invariants (id pattern,\n * description length, top-level freeze, \"defineStorage (AIP-35): …\"\n * error prefix) run uniformly with every other AIP defineX.\n *\n * Field-level validation runs the schema-derived zod from\n * `./schema.ts` against the manifest portion of the input. The\n * AIP-43 runtime slots (`factory`, `capabilities`) are HOST-OPAQUE\n * TS-runtime metadata — they don't exist in the AIP-35 frontmatter\n * schema, so we strip them before validation and re-attach them in\n * `build`. The zod schema stays `.strict()` (typo-catching for MD\n * authors); runtime callers get the extra slots via the input type.\n *\n * Generic params:\n *   TFactory      — host-typed factory function shape (e.g. a Mastra\n *                   `(input) => MastraFilesystem` for the Guilde host).\n *                   Defaults to `unknown`.\n *   TCapabilities — opaque metadata the registry queries on. Per\n *                   AIP-43 § Capability metadata namespace, hosts\n *                   SHOULD agree on conventional keys\n *                   (bridgeable / transport / pairsWith / serverReachable).\n */\nconst defineStorageInner = createDoctype<\n  StorageRuntimeInput,\n  StorageRuntimeHandle\n>({\n  aip: 35,\n  name: \"storage\",\n  readDescription: false,\n  // AIP-35 makes `id` standalone-only — inline storage blocks (every\n  // host registration we care about) carry only `provider` + `config`.\n  // Fall back to `provider` for the cross-AIP id-pattern check; the\n  // resolution order mirrors AIP-43 § Identity (id → provider → slug).\n  readIdentity: def => {\n    if (typeof def.id === \"string\" && def.id.length > 0) return def.id\n    return def.provider\n  },\n  validate(def) {\n    // Strip runtime-only slots before AIP-35 schema validation —\n    // they're not part of the manifest spec, can't round-trip\n    // through YAML, and adding them to the strict schema would mean\n    // every STORAGE.md author has to know about TS internals.\n    const { factory: _factory, capabilities: _capabilities, ...manifest } = def\n    const result = storageFrontmatterSchema.safeParse(manifest)\n    if (!result.success) {\n      throw new Error(\n        `defineStorage (AIP-35): ${result.error.issues\n          .map(i => `${i.path.join(\".\")}: ${i.message}`)\n          .join(\"; \")}`,\n      )\n    }\n    // TODO: spec-35-specific cross-field rules (if/then/allOf in\n    // the JSON Schema) — those don't translate to zod cleanly and\n    // belong here. See @agentproto/operator's autonomy=gated rule.\n  },\n  build(def) {\n    // Re-attach the runtime slots after validation. Capabilities are\n    // shallow-frozen here so registry consumers can rely on\n    // immutability; factory is left as-is (it's a function ref).\n    const { factory, capabilities, ...manifest } = def\n    return {\n      ...manifest,\n      ...(factory !== undefined ? { factory } : {}),\n      ...(capabilities !== undefined\n        ? { capabilities: Object.freeze({ ...capabilities }) }\n        : {}),\n    } as StorageRuntimeHandle\n  },\n})\n\n/**\n * Type-aware wrapper preserving `TFactory` / `TCapabilities` generics\n * across the call (the underlying `createDoctype` factory is invariant\n * over its TDef/THandle pair, so we expose the parametric face here).\n */\nexport function defineStorage<\n  TFactory = unknown,\n  TCapabilities extends Record<string, unknown> = Record<string, unknown>,\n>(\n  definition: StorageRuntimeInput<TFactory, TCapabilities>,\n): StorageRuntimeHandle<TFactory, TCapabilities> {\n  return defineStorageInner(\n    definition as StorageRuntimeInput,\n  ) as StorageRuntimeHandle<TFactory, TCapabilities>\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,136 @@
+import { S as StorageRuntimeInput, a as StorageRuntimeHandle } from './types-DZAjXcqA.js';
+export { b as StorageDefinition, c as StorageHandle } from './types-DZAjXcqA.js';
+
+/**
+ * Type-aware wrapper preserving `TFactory` / `TCapabilities` generics
+ * across the call (the underlying `createDoctype` factory is invariant
+ * over its TDef/THandle pair, so we expose the parametric face here).
+ */
+declare function defineStorage<TFactory = unknown, TCapabilities extends Record<string, unknown> = Record<string, unknown>>(definition: StorageRuntimeInput<TFactory, TCapabilities>): StorageRuntimeHandle<TFactory, TCapabilities>;
+
+/**
+ * WorkspaceSync — the imperative counterpart to the AIP-35 `sync`
+ * policy block (the `pull` / `commit` / `push` sub-blocks). A provider
+ * that backs a workspace with a remote origin (git repo, bucket)
+ * implements this to seed a local working tree FROM the origin (`pull`)
+ * and materialise local writes BACK to it (`push`).
+ *
+ * This is `sync.mode: "pull-push"` made concrete: the local filesystem
+ * stays the runtime truth (fast, offline-capable, the "filesystem on
+ * sait jamais" safety), while the remote repo is the durable, visible,
+ * versioned origin. Contrast `sync.mode: "canonical"`, where the
+ * provider's MastraFilesystem IS the live backing and every read/write
+ * hits the remote per-file — that mode needs no WorkspaceSync.
+ *
+ * Both consumers share one contract:
+ *   - a cloud workstation seeds its sandbox on spawn, pushes on close
+ *   - a corpus seeds its workspace on resolve, pushes on promote
+ *
+ * Spec: https://agentproto.sh/docs/aip-35 (sync block) + AIP-37 (hooks)
+ */
+/**
+ * The minimal tree surface `pull` / `push` operate on. A structural
+ * subset of `FsPort` (@agentproto/corpus) — declared here so
+ * `@agentproto/storage` stays dependency-free; any `FsPort` or
+ * `MastraFilesystem` adapter satisfies it by shape. Paths are
+ * workspace-relative (no leading slash); `""` / `.` is the root.
+ */
+interface SyncTree {
+    exists(path: string): Promise<boolean>;
+    readFile(path: string): Promise<string>;
+    writeFile(path: string, content: string): Promise<void>;
+    /** Recursive listing — workspace-relative paths of every file under
+     *  `path`. Skips dot-directories (matches FsPort.walk). */
+    walk(path: string): Promise<readonly string[]>;
+}
+interface PullResult {
+    /** False when the tree was already populated and `force` was unset. */
+    seeded: boolean;
+    files: number;
+    bytes: number;
+    message: string;
+}
+type PushResult = {
+    kind: "pushed";
+    /** The ref the commit landed on (branch name). */
+    ref: string;
+    commit?: string;
+    prUrl?: string;
+    prNumber?: number;
+    files: number;
+    /** Bytes materialised to the origin, when the provider tracks it. */
+    bytes?: number;
+    /** Files the provider intentionally left behind (size caps,
+     *  exclude rules) — telemetry, not a failure. */
+    filesSkipped?: number;
+    /** Non-fatal errors during a best-effort push. The push still
+     *  landed; these are per-file warnings a UI may surface. */
+    errors?: readonly string[];
+    message: string;
+}
+/** Working tree matches the origin — nothing to push. */
+ | {
+    kind: "no_changes";
+    message: string;
+}
+/** No credential resolved for the origin — refuse rather than fall
+ *  back to a host token (would cross-tenant commits). */
+ | {
+    kind: "no_credentials";
+    message: string;
+}
+/** Credential reads the origin but cannot write to it. */
+ | {
+    kind: "no_permission";
+    message: string;
+} | {
+    kind: "failed";
+    message: string;
+};
+interface PushOptions {
+    /** Short label for the commit / branch (e.g. operator or run id). */
+    label?: string;
+    /** Human summary woven into the commit message / PR body. */
+    summary?: string;
+}
+/**
+ * Pull-push lifecycle for a remote-backed workspace. Providers expose
+ * this alongside their `MastraFilesystem`; callers feature-detect it
+ * (`if ("pull" in fs)`) — no parallel registry, the provider id is the
+ * single dispatch key.
+ */
+interface WorkspaceSync {
+    /**
+     * Seed `tree` from the remote origin. Idempotent. Refuses to clobber
+     * a non-empty tree unless `opts.force` — a fresh workspace starts
+     * empty, but a misrouted call against a warm tree must not silently
+     * overwrite ongoing work.
+     */
+    pull(tree: SyncTree, opts?: {
+        force?: boolean;
+    }): Promise<PullResult>;
+    /**
+     * Materialise the current `tree` state to the origin as a single
+     * commit (plus a PR when the provider's `sync.push.prPolicy` calls
+     * for one). A no-op when the tree matches the origin.
+     */
+    push(tree: SyncTree, opts?: PushOptions): Promise<PushResult>;
+}
+/** Feature-detect the sync capability on a resolved filesystem. */
+declare function hasWorkspaceSync(fs: unknown): fs is WorkspaceSync;
+
+/**
+ * @agentproto/storage — AIP-35 STORAGE.md `defineStorage` reference impl.
+ *
+ * A composable schema block defining the `storage` field — provider, config, sync semantics, auth ref, exclude rules — for any manifest that names a backing store. Reused by WORKSPACE.md (AIP-34) and any future manifest that names persistent state. Inline or ref, mirroring AIP-17 RUNNER and AIP-19 SECRETS.
+ *
+ * Spec: https://agentproto.sh/docs/aip-35
+ *
+ * Authoring paths:
+ *   - TS:  `defineStorage({...})` → `StorageHandle`
+ *   - MD:  `parseStorageManifest(src) → storageFromManifest({...})` → `StorageHandle`
+ */
+declare const SPEC_NAME: "agentstorage/v1";
+declare const SPEC_VERSION: "1.0.0-alpha";
+
+export { type PullResult, type PushOptions, type PushResult, SPEC_NAME, SPEC_VERSION, StorageRuntimeHandle, StorageRuntimeInput, type SyncTree, type WorkspaceSync, defineStorage, hasWorkspaceSync };

package/dist/index.mjs

@@ -0,0 +1,19 @@
+export { defineStorage } from './chunk-JMBOQNBX.mjs';
+
+/**
+ * @agentproto/storage v0.1.0-alpha
+ * AIP-35 STORAGE.md `defineStorage` reference implementation.
+ */
+
+// src/workspace-sync.ts
+function hasWorkspaceSync(fs) {
+  return typeof fs === "object" && fs !== null && typeof fs.pull === "function" && typeof fs.push === "function";
+}
+
+// src/index.ts
+var SPEC_NAME = "agentstorage/v1";
+var SPEC_VERSION = "1.0.0-alpha";
+
+export { SPEC_NAME, SPEC_VERSION, hasWorkspaceSync };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/workspace-sync.ts","../src/index.ts"],"names":[],"mappings":";;;;;;;;AAwGO,SAAS,iBAAiB,EAAA,EAAkC;AACjE,EAAA,OACE,OAAO,EAAA,KAAO,QAAA,IACd,EAAA,KAAO,IAAA,IACP,OAAQ,EAAA,CAAqB,IAAA,KAAS,UAAA,IACtC,OAAQ,EAAA,CAAqB,IAAA,KAAS,UAAA;AAE1C;;;ACnGO,IAAM,SAAA,GAAY;AAClB,IAAM,YAAA,GAAe","file":"index.mjs","sourcesContent":["/**\n * WorkspaceSync — the imperative counterpart to the AIP-35 `sync`\n * policy block (the `pull` / `commit` / `push` sub-blocks). A provider\n * that backs a workspace with a remote origin (git repo, bucket)\n * implements this to seed a local working tree FROM the origin (`pull`)\n * and materialise local writes BACK to it (`push`).\n *\n * This is `sync.mode: \"pull-push\"` made concrete: the local filesystem\n * stays the runtime truth (fast, offline-capable, the \"filesystem on\n * sait jamais\" safety), while the remote repo is the durable, visible,\n * versioned origin. Contrast `sync.mode: \"canonical\"`, where the\n * provider's MastraFilesystem IS the live backing and every read/write\n * hits the remote per-file — that mode needs no WorkspaceSync.\n *\n * Both consumers share one contract:\n *   - a cloud workstation seeds its sandbox on spawn, pushes on close\n *   - a corpus seeds its workspace on resolve, pushes on promote\n *\n * Spec: https://agentproto.sh/docs/aip-35 (sync block) + AIP-37 (hooks)\n */\n\n/**\n * The minimal tree surface `pull` / `push` operate on. A structural\n * subset of `FsPort` (@agentproto/corpus) — declared here so\n * `@agentproto/storage` stays dependency-free; any `FsPort` or\n * `MastraFilesystem` adapter satisfies it by shape. Paths are\n * workspace-relative (no leading slash); `\"\"` / `.` is the root.\n */\nexport interface SyncTree {\n  exists(path: string): Promise<boolean>\n  readFile(path: string): Promise<string>\n  writeFile(path: string, content: string): Promise<void>\n  /** Recursive listing — workspace-relative paths of every file under\n   *  `path`. Skips dot-directories (matches FsPort.walk). */\n  walk(path: string): Promise<readonly string[]>\n}\n\nexport interface PullResult {\n  /** False when the tree was already populated and `force` was unset. */\n  seeded: boolean\n  files: number\n  bytes: number\n  message: string\n}\n\nexport type PushResult =\n  | {\n      kind: \"pushed\"\n      /** The ref the commit landed on (branch name). */\n      ref: string\n      commit?: string\n      prUrl?: string\n      prNumber?: number\n      files: number\n      /** Bytes materialised to the origin, when the provider tracks it. */\n      bytes?: number\n      /** Files the provider intentionally left behind (size caps,\n       *  exclude rules) — telemetry, not a failure. */\n      filesSkipped?: number\n      /** Non-fatal errors during a best-effort push. The push still\n       *  landed; these are per-file warnings a UI may surface. */\n      errors?: readonly string[]\n      message: string\n    }\n  /** Working tree matches the origin — nothing to push. */\n  | { kind: \"no_changes\"; message: string }\n  /** No credential resolved for the origin — refuse rather than fall\n   *  back to a host token (would cross-tenant commits). */\n  | { kind: \"no_credentials\"; message: string }\n  /** Credential reads the origin but cannot write to it. */\n  | { kind: \"no_permission\"; message: string }\n  | { kind: \"failed\"; message: string }\n\nexport interface PushOptions {\n  /** Short label for the commit / branch (e.g. operator or run id). */\n  label?: string\n  /** Human summary woven into the commit message / PR body. */\n  summary?: string\n}\n\n/**\n * Pull-push lifecycle for a remote-backed workspace. Providers expose\n * this alongside their `MastraFilesystem`; callers feature-detect it\n * (`if (\"pull\" in fs)`) — no parallel registry, the provider id is the\n * single dispatch key.\n */\nexport interface WorkspaceSync {\n  /**\n   * Seed `tree` from the remote origin. Idempotent. Refuses to clobber\n   * a non-empty tree unless `opts.force` — a fresh workspace starts\n   * empty, but a misrouted call against a warm tree must not silently\n   * overwrite ongoing work.\n   */\n  pull(tree: SyncTree, opts?: { force?: boolean }): Promise<PullResult>\n\n  /**\n   * Materialise the current `tree` state to the origin as a single\n   * commit (plus a PR when the provider's `sync.push.prPolicy` calls\n   * for one). A no-op when the tree matches the origin.\n   */\n  push(tree: SyncTree, opts?: PushOptions): Promise<PushResult>\n}\n\n/** Feature-detect the sync capability on a resolved filesystem. */\nexport function hasWorkspaceSync(fs: unknown): fs is WorkspaceSync {\n  return (\n    typeof fs === \"object\" &&\n    fs !== null &&\n    typeof (fs as WorkspaceSync).pull === \"function\" &&\n    typeof (fs as WorkspaceSync).push === \"function\"\n  )\n}\n","/**\n * @agentproto/storage — AIP-35 STORAGE.md `defineStorage` reference impl.\n *\n * A composable schema block defining the `storage` field — provider, config, sync semantics, auth ref, exclude rules — for any manifest that names a backing store. Reused by WORKSPACE.md (AIP-34) and any future manifest that names persistent state. Inline or ref, mirroring AIP-17 RUNNER and AIP-19 SECRETS.\n *\n * Spec: https://agentproto.sh/docs/aip-35\n *\n * Authoring paths:\n *   - TS:  `defineStorage({...})` → `StorageHandle`\n *   - MD:  `parseStorageManifest(src) → storageFromManifest({...})` → `StorageHandle`\n */\n\nexport const SPEC_NAME = \"agentstorage/v1\" as const\nexport const SPEC_VERSION = \"1.0.0-alpha\" as const\n\nexport { defineStorage } from \"./define-storage.js\"\nexport type {\n  StorageDefinition,\n  StorageHandle,\n  StorageRuntimeInput,\n  StorageRuntimeHandle,\n} from \"./types.js\"\n\nexport { hasWorkspaceSync } from \"./workspace-sync.js\"\nexport type {\n  WorkspaceSync,\n  SyncTree,\n  PullResult,\n  PushResult,\n  PushOptions,\n} from \"./workspace-sync.js\"\n"]}

package/dist/manifest/index.d.ts

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import { c as StorageHandle } from '../types-DZAjXcqA.js';
+
+/**
+ * AIP-35 STORAGE.md frontmatter zod schema.
+ *
+ * Generated from `resources/aip-35/draft/STORAGE.schema.json` via
+ * json-schema-to-zod. Imported by both `define-storage.ts` (TS path
+ * validation) and `manifest/index.ts` (.md path validation) so every
+ * field-level constraint runs in both authoring paths from a single
+ * source of truth — re-run scaffold-aip to refresh after spec changes.
+ *
+ * Cross-field rules (if/then/allOf in JSON Schema) don't translate
+ * cleanly and live in `define-storage.ts`'s `validate(def)` instead.
+ */
+
+declare const storageFrontmatterSchema: z.ZodObject<{
+    schema: z.ZodOptional<z.ZodLiteral<"storage/v1">>;
+    id: z.ZodOptional<z.ZodString>;
+    version: z.ZodOptional<z.ZodString>;
+    provider: z.ZodString;
+    config: z.ZodRecord<z.ZodString, z.ZodAny>;
+    sync: z.ZodOptional<z.ZodAny>;
+    auth: z.ZodOptional<z.ZodAny>;
+    identity: z.ZodOptional<z.ZodAny>;
+    exclude: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    read_only: z.ZodDefault<z.ZodBoolean>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.core.$strict>;
+type StorageFrontmatter = z.infer<typeof storageFrontmatterSchema>;
+
+/**
+ * AIP-35 STORAGE.md sidecar parser + manifest-to-handle constructor.
+ *
+ * Mirror of `@agentproto/tool/manifest` and `@agentproto/driver/manifest`:
+ * the .md provides metadata; the TS module supplies any spec-specific
+ * runtime bits (schemas, execute bodies, …) that can't live in
+ * frontmatter. Both inputs end up in `defineStorage` so the cross-AIP
+ * invariants run uniformly.
+ *
+ *
+ * The frontmatter zod schema below was generated from
+ * `resources/aip-35/draft/STORAGE.schema.json` via json-schema-to-zod.
+ * Re-run scaffold-aip to refresh after spec changes (or hand-tune
+ * any constraint the converter doesn't capture cleanly).
+ */
+
+interface StorageManifest {
+    frontmatter: StorageFrontmatter;
+    body: string;
+}
+declare function parseStorageManifest(source: string): StorageManifest;
+declare function storageFromManifest(manifest: StorageManifest): StorageHandle;
+
+export { type StorageFrontmatter, type StorageManifest, parseStorageManifest, storageFromManifest, storageFrontmatterSchema };

package/dist/manifest/index.mjs

@@ -0,0 +1,28 @@
+import { storageFrontmatterSchema, defineStorage } from '../chunk-JMBOQNBX.mjs';
+export { storageFrontmatterSchema } from '../chunk-JMBOQNBX.mjs';
+import matter from 'gray-matter';
+
+/**
+ * @agentproto/storage v0.1.0-alpha
+ * AIP-35 STORAGE.md `defineStorage` reference implementation.
+ */
+function parseStorageManifest(source) {
+  const parsed = matter(source);
+  if (Object.keys(parsed.data).length === 0) {
+    throw new Error("parseStorageManifest: missing or empty frontmatter");
+  }
+  const result = storageFrontmatterSchema.safeParse(parsed.data);
+  if (!result.success) {
+    throw new Error(
+      `parseStorageManifest: invalid frontmatter \u2014 ${result.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`
+    );
+  }
+  return { frontmatter: result.data, body: parsed.content };
+}
+function storageFromManifest(manifest) {
+  return defineStorage(manifest.frontmatter);
+}
+
+export { parseStorageManifest, storageFromManifest };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/manifest/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/manifest/index.ts"],"names":[],"mappings":";;;;;;;;AA8BO,SAAS,qBAAqB,MAAA,EAAiC;AACpE,EAAA,MAAM,MAAA,GAAS,OAAO,MAAM,CAAA;AAC5B,EAAA,IAAI,OAAO,IAAA,CAAK,MAAA,CAAO,IAAI,CAAA,CAAE,WAAW,CAAA,EAAG;AACzC,IAAA,MAAM,IAAI,MAAM,oDAAoD,CAAA;AAAA,EACtE;AACA,EAAA,MAAM,MAAA,GAAS,wBAAA,CAAyB,SAAA,CAAU,MAAA,CAAO,IAAI,CAAA;AAC7D,EAAA,IAAI,CAAC,OAAO,OAAA,EAAS;AACnB,IAAA,MAAM,IAAI,KAAA;AAAA,MACR,CAAA,iDAAA,EAA+C,OAAO,KAAA,CAAM,MAAA,CACzD,IAAI,CAAC,CAAA,KAAM,GAAG,CAAA,CAAE,IAAA,CAAK,KAAK,GAAG,CAAC,KAAK,CAAA,CAAE,OAAO,EAAE,CAAA,CAC9C,IAAA,CAAK,IAAI,CAAC,CAAA;AAAA,KACf;AAAA,EACF;AACA,EAAA,OAAO,EAAE,WAAA,EAAa,MAAA,CAAO,IAAA,EAAM,IAAA,EAAM,OAAO,OAAA,EAAQ;AAC1D;AAEO,SAAS,oBAAoB,QAAA,EAA0C;AAK5E,EAAA,OAAO,aAAA,CAAc,SAAS,WAA2C,CAAA;AAC3E","file":"index.mjs","sourcesContent":["/**\n * AIP-35 STORAGE.md sidecar parser + manifest-to-handle constructor.\n *\n * Mirror of `@agentproto/tool/manifest` and `@agentproto/driver/manifest`:\n * the .md provides metadata; the TS module supplies any spec-specific\n * runtime bits (schemas, execute bodies, …) that can't live in\n * frontmatter. Both inputs end up in `defineStorage` so the cross-AIP\n * invariants run uniformly.\n *\n *\n * The frontmatter zod schema below was generated from\n * `resources/aip-35/draft/STORAGE.schema.json` via json-schema-to-zod.\n * Re-run scaffold-aip to refresh after spec changes (or hand-tune\n * any constraint the converter doesn't capture cleanly).\n */\n\nimport matter from \"gray-matter\"\nimport { storageFrontmatterSchema, type StorageFrontmatter } from \"../schema.js\"\nimport { defineStorage } from \"../define-storage.js\"\nimport type { StorageDefinition, StorageHandle } from \"../types.js\"\n\n// Re-export so consumers can import the schema + inferred type either\n// from \"@@agentproto/storage/manifest\" or directly from \"@@agentproto/storage/schema\".\nexport { storageFrontmatterSchema, type StorageFrontmatter }\n\nexport interface StorageManifest {\n  frontmatter: StorageFrontmatter\n  body: string\n}\n\nexport function parseStorageManifest(source: string): StorageManifest {\n  const parsed = matter(source)\n  if (Object.keys(parsed.data).length === 0) {\n    throw new Error(\"parseStorageManifest: missing or empty frontmatter\")\n  }\n  const result = storageFrontmatterSchema.safeParse(parsed.data)\n  if (!result.success) {\n    throw new Error(\n      `parseStorageManifest: invalid frontmatter — ${result.error.issues\n        .map((i) => `${i.path.join(\".\")}: ${i.message}`)\n        .join(\"; \")}`,\n    )\n  }\n  return { frontmatter: result.data, body: parsed.content }\n}\n\nexport function storageFromManifest(manifest: StorageManifest): StorageHandle {\n  // The zod-validated frontmatter is structurally compatible with\n  // StorageDefinition; the cast pins the typing once the manifest\n  // schema and the TS interface diverge (e.g. handle has frozen fields\n  // a literal config doesn't carry yet).\n  return defineStorage(manifest.frontmatter as unknown as StorageDefinition)\n}\n"]}

package/dist/types-DZAjXcqA.d.ts

@@ -0,0 +1,166 @@
+/**
+ * AIP-35 StorageDefinition + StorageHandle.
+ *
+ * `StorageDefinition` was generated from
+ * `resources/aip-35/draft/STORAGE.schema.json` via json-schema-to-typescript.
+ * `StorageHandle` is the readonly view of the same shape; tighten it
+ * by hand for fields that get defaults applied in build().
+ */
+type IdentityRefEntry = {
+    name: string;
+    email: string;
+    avatar?: string;
+    gpg_key?: string;
+    role?: string;
+    metadata?: {};
+    [k: string]: unknown;
+} | {
+    ref: string;
+    role?: string;
+    [k: string]: unknown;
+} | {
+    file: string;
+    role?: string;
+    [k: string]: unknown;
+};
+/**
+ * Validates the YAML frontmatter portion of an AIP-35 STORAGE.md manifest, OR the inline form embedded in any other manifest's `storage:` block. Filesystem-only — sandbox-shaped backends (e2b/modal/...) live in AIP-36 SANDBOX.md.
+ */
+interface StorageDefinition {
+    /**
+     * Standalone-only. Identifies the doctype + version. Absent when the block is inlined in another manifest.
+     */
+    schema?: "storage/v1";
+    /**
+     * Standalone-only. Globally addressable id `@<owner-slug>/<storage-slug>`.
+     */
+    id?: string;
+    /**
+     * Standalone-only. Spec version of THIS file. Bump on breaking shape change.
+     */
+    version?: string;
+    /**
+     * Backend kind. Day-1 enumerated set: cloud-bucket | self-bucket | github | local-fs | dev-local | mastra-s3 | mastra-azure. Hosts MAY register additional ids; the schema accepts any non-empty string and host-side validation narrows.
+     */
+    provider: string;
+    /**
+     * Provider-specific connection fields. Shape varies per provider (see AIP-35 §Provider config shapes).
+     */
+    config: {};
+    sync?: SyncBlock;
+    auth?: AuthBlock;
+    /**
+     * AIP-23 identity-ref block — commit author(s) for syncing providers (github). Supports multi-attribution (primary + co-authors).
+     */
+    identity?: IdentityRefEntry | [IdentityRefEntry, ...IdentityRefEntry[]];
+    /**
+     * Paths NOT mirrored to the backing store. Glob-ish, prefix-matched.
+     */
+    exclude?: string[];
+    /**
+     * Reject writes at the storage layer.
+     */
+    read_only?: boolean;
+    /**
+     * Free-form, namespaced. Authors MAY stash adapter-specific hints under namespaced keys.
+     */
+    metadata?: {
+        [k: string]: unknown;
+    };
+}
+/**
+ * Sync semantics. Lifecycle triggers reference AIP-37 event names.
+ */
+interface SyncBlock {
+    mode?: "canonical" | "pull-push" | "watch";
+    pull?: {
+        /**
+         * AIP-37 lifecycle event name. Standard: workspace-open | turn-start | manual. Aliases (per-turn, each-write) resolve via AIP-37.
+         */
+        on?: string;
+        /**
+         * Cache validity for pull-push providers (e.g. github clone).
+         */
+        ttl_seconds?: number;
+    };
+    commit?: {
+        /**
+         * AIP-37 event name. Common: each-write | per-turn | per-conversation | manual.
+         */
+        on?: string;
+        /**
+         * Debounce window for each-write commit mode.
+         */
+        batch_window_ms?: number;
+        /**
+         * Template for commit message. Provider-specific tokens (e.g. {{operator}}, {{summary}}).
+         */
+        message_template?: string;
+    };
+    push?: {
+        /**
+         * AIP-37 event name. Common: per-commit | per-turn | per-conversation | manual.
+         */
+        on?: string;
+        /**
+         * Github only. Where commits land.
+         */
+        branch_policy?: "main" | "per-conversation" | "per-turn";
+        /**
+         * Github only. Whether to open PRs automatically.
+         */
+        pr_policy?: "none" | "auto" | "manual";
+    };
+    conflict?: {
+        policy?: "rebase" | "merge" | "abort" | "manual" | "last-writer-wins" | "split-conflicts";
+    };
+}
+/**
+ * Reference to AIP-19 SECRETS.md (or future ENV.md) for credentials.
+ */
+interface AuthBlock {
+    /**
+     * Path or registry slug pointing to a SECRETS.md (or future ENV.md) inventory.
+     */
+    ref?: string;
+    state?: {
+        /**
+         * Env-var names this consumer expects to be revealed from the referenced inventory.
+         */
+        env?: string[];
+    };
+}
+type StorageHandle = Readonly<StorageDefinition>;
+/**
+ * In-TS authoring shape — what callers pass to `defineStorage(...)`
+ * when constructing a handle programmatically (vs. parsing one from
+ * STORAGE.md). Extends `StorageDefinition` with two optional
+ * host-runtime slots that don't exist in the manifest schema.
+ */
+interface StorageRuntimeInput<TFactory = unknown, TCapabilities extends Record<string, unknown> = Record<string, unknown>> extends StorageDefinition {
+    /**
+     * Host-typed factory function. Given config (and optionally a host-
+     * specific input bundle), returns a usable filesystem implementation
+     * in whatever shape the host expects (Mastra `MastraFilesystem`,
+     * MCP client, etc). The slot is opaque to agentproto; the host owns
+     * the type.
+     */
+    factory?: TFactory;
+    /**
+     * Free-form metadata the registry indexes for cross-handle lookups.
+     * Suggested namespace conventions live in the AIP-43 § Capability
+     * metadata namespace section; the schema is otherwise unconstrained.
+     */
+    capabilities?: TCapabilities;
+}
+/**
+ * What `defineStorage(...)` returns. Carries `factory` + `capabilities`
+ * through unchanged so registry consumers and host code can read them
+ * off the handle.
+ */
+type StorageRuntimeHandle<TFactory = unknown, TCapabilities extends Record<string, unknown> = Record<string, unknown>> = Readonly<StorageDefinition> & {
+    readonly factory?: TFactory;
+    readonly capabilities?: Readonly<TCapabilities>;
+};
+
+export type { StorageRuntimeInput as S, StorageRuntimeHandle as a, StorageDefinition as b, StorageHandle as c };

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@agentproto/storage",
+  "version": "0.1.0-alpha.0",
+  "description": "@agentproto/storage — AIP-35 STORAGE.md reference implementation. A composable schema block defining the `storage` field — provider, config, sync semantics, auth ref, exclude rules — for any manifest that names a backing store. Reused by WORKSPACE.md (AIP-34) and any future manifest that names persistent state. Inline or ref, mirroring AIP-17 RUNNER and AIP-19 SECRETS.",
+  "keywords": [
+    "agentproto",
+    "aip-35",
+    "storage",
+    "defineStorage",
+    "open-standard",
+    "agentic"
+  ],
+  "homepage": "https://agentproto.sh/docs/aip-35",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/agentproto/ts",
+    "directory": "packages/storage"
+  },
+  "bugs": {
+    "url": "https://github.com/agentproto/ts/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.mjs",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "default": "./dist/index.mjs"
+    },
+    "./manifest": {
+      "types": "./dist/manifest/index.d.ts",
+      "import": "./dist/manifest/index.mjs",
+      "default": "./dist/manifest/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "zod": "^4.4.3",
+    "@agentproto/define-doctype": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.2",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@agentproto/tooling": "0.1.0-alpha.0"
+  },
+  "scripts": {
+    "dev": "tsup --watch",
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "check-types": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest"
+  }
+}