@ottimis/jack-provider-sdk 0.9.0 → 0.10.0

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.
Files changed (4) hide show
  1. package/dist/sandbox.d.ts +29 -17
  2. package/dist/sandbox.d.ts.map +1 -1
  3. package/package.json +1 -1
  4. package/src/sandbox.ts +29 -17
package/dist/sandbox.d.ts CHANGED
@@ -30,29 +30,35 @@
30
30
  * free to host wherever they like.
31
31
  */
32
32
  /**
33
- * Mount the provider's host-side config directory into the container.
34
- * Most providers persist auth + sessions + per-user settings in a dotfile
35
- * dir under `$HOME` (Claude `~/.claude`, Codex `~/.codex`, Gemini
36
- * `~/.gemini`). The host mounts this dir into the container at
37
- * {@link containerPath} so the CLI inside the container has access to the
38
- * same auth state as the host.
33
+ * Mount a provider-side config artifact (directory or file) into the
34
+ * container. Most providers persist auth + sessions + per-user settings in
35
+ * a dotfile dir under `$HOME` (Claude `~/.claude`, Codex `~/.codex`,
36
+ * Gemini `~/.gemini`); some additionally need a sibling config file
37
+ * mounted alongside (Claude `~/.claude.json` is a good example — the CLI
38
+ * reads it as the "main config" separate from the dotfile dir). The host
39
+ * mounts each entry into the container at {@link containerPath} so the CLI
40
+ * inside the container has access to the same state as the host.
39
41
  *
40
- * Read-only by default — the container shouldn't be writing back to the
41
- * user's persistent config from inside the sandbox. Set `readOnly: false`
42
- * only when the provider's CLI genuinely needs to mutate state inside the
43
- * config dir (e.g. session JSONL append).
42
+ * Read-only is recommended whenever the provider's CLI doesn't genuinely
43
+ * need to mutate state. Set `readOnly: false` when the CLI writes back —
44
+ * Claude writes session-env, project history, MCP additions; Codex appends
45
+ * thread JSONL; etc. The trade-off when RW is enabled: sandbox sessions
46
+ * share the same on-disk state as the host CLI (history, project state,
47
+ * MCP edits). If you need credential isolation, build a copy-on-write
48
+ * scratch volume — the {@link SandboxApi} contract doesn't impose one.
44
49
  */
45
50
  export type SandboxConfigMount = {
46
51
  /**
47
52
  * Absolute host path. Provider implementations resolve this lazily — call
48
- * `os.homedir()` + `path.join(...)` at the time `configMount` is read,
53
+ * `os.homedir()` + `path.join(...)` at the time `configMounts` is read,
49
54
  * not at module-load time, so test environments and per-process HOME
50
- * overrides work correctly.
55
+ * overrides work correctly. May point to either a directory or a single
56
+ * file — Docker's bind mount accepts both.
51
57
  */
52
58
  hostPath: string;
53
59
  /** Absolute container path. */
54
60
  containerPath: string;
55
- /** When `true`, the host adds `:ro` to the bind. Default: `true` recommended. */
61
+ /** When `true`, the host adds `:ro` to the bind. */
56
62
  readOnly: boolean;
57
63
  };
58
64
  /**
@@ -83,11 +89,17 @@ export interface SandboxApi {
83
89
  */
84
90
  readonly binaryName: string;
85
91
  /**
86
- * Mount the provider's host-side config directory into the container.
87
- * Optional — providers that are stateless on the host (none today)
88
- * leave this undefined.
92
+ * Mount provider-side config artifacts (directories and/or files) into
93
+ * the container. Optional — providers that are stateless on the host
94
+ * (none today) leave this undefined or pass an empty array.
95
+ *
96
+ * Multiple entries support providers whose CLI splits state across more
97
+ * than one path (e.g. Claude needs both `~/.claude/` for the dotfile dir
98
+ * and `~/.claude.json` for the main config file). Order is preserved
99
+ * but mounts are independent — if two entries overlap, Docker resolves
100
+ * them in declaration order.
89
101
  */
90
- readonly configMount?: SandboxConfigMount;
102
+ readonly configMounts?: readonly SandboxConfigMount[];
91
103
  /**
92
104
  * Optional environment extras to inject into the container. Layered AFTER
93
105
  * the spawn-arg env so provider-specific overrides can win, but BEFORE
package/dist/sandbox.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;;;OAKG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAA;IACrB,iFAAiF;IACjF,QAAQ,EAAE,OAAO,CAAA;CAClB,CAAA;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;;;;;OASG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAE7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAE3B;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAA;IAEzC;;;;;;;;;;OAUG;IACH,SAAS,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACrC"}
1
+ {"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B;;;;;;OAMG;IACH,QAAQ,EAAE,MAAM,CAAA;IAChB,+BAA+B;IAC/B,aAAa,EAAE,MAAM,CAAA;IACrB,oDAAoD;IACpD,QAAQ,EAAE,OAAO,CAAA;CAClB,CAAA;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB;;;;;;;;;OASG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAA;IAE7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAE3B;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAA;IAErD;;;;;;;;;;OAUG;IACH,SAAS,CAAC,IAAI,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACrC"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ottimis/jack-provider-sdk",
3
- "version": "0.9.0",
3
+ "version": "0.10.0",
4
4
  "description": "Plugin contract for AI provider integrations in Jack — backend interface, capability matrix, spawner primitives, knowledge context. Consumed both by in-tree providers and external packages.",
5
5
  "license": "MIT",
6
6
  "repository": {
package/src/sandbox.ts CHANGED
@@ -31,29 +31,35 @@
31
31
  */
32
32
 
33
33
  /**
34
- * Mount the provider's host-side config directory into the container.
35
- * Most providers persist auth + sessions + per-user settings in a dotfile
36
- * dir under `$HOME` (Claude `~/.claude`, Codex `~/.codex`, Gemini
37
- * `~/.gemini`). The host mounts this dir into the container at
38
- * {@link containerPath} so the CLI inside the container has access to the
39
- * same auth state as the host.
34
+ * Mount a provider-side config artifact (directory or file) into the
35
+ * container. Most providers persist auth + sessions + per-user settings in
36
+ * a dotfile dir under `$HOME` (Claude `~/.claude`, Codex `~/.codex`,
37
+ * Gemini `~/.gemini`); some additionally need a sibling config file
38
+ * mounted alongside (Claude `~/.claude.json` is a good example — the CLI
39
+ * reads it as the "main config" separate from the dotfile dir). The host
40
+ * mounts each entry into the container at {@link containerPath} so the CLI
41
+ * inside the container has access to the same state as the host.
40
42
  *
41
- * Read-only by default — the container shouldn't be writing back to the
42
- * user's persistent config from inside the sandbox. Set `readOnly: false`
43
- * only when the provider's CLI genuinely needs to mutate state inside the
44
- * config dir (e.g. session JSONL append).
43
+ * Read-only is recommended whenever the provider's CLI doesn't genuinely
44
+ * need to mutate state. Set `readOnly: false` when the CLI writes back —
45
+ * Claude writes session-env, project history, MCP additions; Codex appends
46
+ * thread JSONL; etc. The trade-off when RW is enabled: sandbox sessions
47
+ * share the same on-disk state as the host CLI (history, project state,
48
+ * MCP edits). If you need credential isolation, build a copy-on-write
49
+ * scratch volume — the {@link SandboxApi} contract doesn't impose one.
45
50
  */
46
51
  export type SandboxConfigMount = {
47
52
  /**
48
53
  * Absolute host path. Provider implementations resolve this lazily — call
49
- * `os.homedir()` + `path.join(...)` at the time `configMount` is read,
54
+ * `os.homedir()` + `path.join(...)` at the time `configMounts` is read,
50
55
  * not at module-load time, so test environments and per-process HOME
51
- * overrides work correctly.
56
+ * overrides work correctly. May point to either a directory or a single
57
+ * file — Docker's bind mount accepts both.
52
58
  */
53
59
  hostPath: string
54
60
  /** Absolute container path. */
55
61
  containerPath: string
56
- /** When `true`, the host adds `:ro` to the bind. Default: `true` recommended. */
62
+ /** When `true`, the host adds `:ro` to the bind. */
57
63
  readOnly: boolean
58
64
  }
59
65
 
@@ -87,11 +93,17 @@ export interface SandboxApi {
87
93
  readonly binaryName: string
88
94
 
89
95
  /**
90
- * Mount the provider's host-side config directory into the container.
91
- * Optional — providers that are stateless on the host (none today)
92
- * leave this undefined.
96
+ * Mount provider-side config artifacts (directories and/or files) into
97
+ * the container. Optional — providers that are stateless on the host
98
+ * (none today) leave this undefined or pass an empty array.
99
+ *
100
+ * Multiple entries support providers whose CLI splits state across more
101
+ * than one path (e.g. Claude needs both `~/.claude/` for the dotfile dir
102
+ * and `~/.claude.json` for the main config file). Order is preserved
103
+ * but mounts are independent — if two entries overlap, Docker resolves
104
+ * them in declaration order.
93
105
  */
94
- readonly configMount?: SandboxConfigMount
106
+ readonly configMounts?: readonly SandboxConfigMount[]
95
107
 
96
108
  /**
97
109
  * Optional environment extras to inject into the container. Layered AFTER