12 KiB
markup, title, description, import
| markup | title | description | import | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| occlusion | ext/ai/sandbox | CoW trial workspace for AI-generated Marqdo: open / run / diff / commit. Native work lives in plugins/agent (`sandbox_*` → host_query). |
|
Load the agent plugin once per call (same pattern as other ext/ai helpers).
Capability profiles are GFM tables under ## profile (readable authority; open / inspect echo them). Do not invent a second table dialect.
CoW trial operations belong here; attaching a sandbox profile to another result does not isolate execution. The AI entry explains the relation to model and agent resources. A trial produces inspectable changes; promotion is a separate existing operation with its own checks. Keep cancellation, failed execution and explicit promotion visible, and never equate a generated source file with a committed successful outcome.
ensure_plugin
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | No business value on completion; a missing native plugin reports the cause and exits this run. |
Resolve and load the required native ABI plugin; missing binaries report a diagnostic message and stop this run.
We retain p = Locate the installed native plugin.
We [Print the prepared message](print(text="ext/ai/sandbox: native agent plugin not found (build marqdo_plugin_agent or marqdo ext add agent)")). We End this run with the selected exit status.
profile
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| name | any | "default" | Name registered or looked up by this operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Named caps row as a map table (name, fs_write, exec, net, plugin). Unknown names → default. Catalog (documentation + authority): |
Use name="default" as the inputs for this operation.
Named caps row as a map table (name, fs_write, exec, net, plugin). Unknown names → default.
Catalog (documentation + authority):
| name | fs_write | exec | net | plugin |
|---|---|---|---|---|
| default | true | false | false | false |
| readonly | false | false | false | false |
name== "readonly" **row = **
| name | fs_write | exec | net | plugin |
|---|---|---|---|---|
| readonly | false | false | false | false |
**row = **
| name | fs_write | exec | net | plugin |
|---|---|---|---|---|
| default | true | false | false | false |
Return row.
open_native
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| root | any | None | Explicit root directory for discovery or isolated execution |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Native CoW open (plugin ABI italic return). Prefer ## open for the profile-aware facade. |
Use root=None as the inputs for this operation.
Native CoW open (plugin ABI italic return). Prefer ## open for the profile-aware facade.
We Load the native plugin required by this operation.
rootReturn Native CoW open (plugin ABI italic return). Prefer ## open for the profile-aware facade..-
Return Native CoW open (plugin ABI italic return). Prefer ## open for the profile-aware facade..
open
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| root | any | None | Explicit root directory for discovery or isolated execution |
| profile | any | "default" | Capability profile selected for the trial |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Open a CoW session. Optional root= (directory). Default: entry file directory. |
Use root=None, profile="default" as the inputs for this operation.
Open a CoW session. Optional root= (directory). Default: entry file directory.
profile= selects the caps row from ## profile (echoed by inspect).
We retain sess = Open native.
We retain prof = Profile.
We retain sess = [Set the profile field in the new record](table.put(in=sess, at="profile", value=prof)).
Return sess.
write
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| path | any | required | Explicit filesystem path; honor the documented filesystem root and operation effects |
| text | any | required | Text supplied to the transformation or adapter |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Write text into the session upper layer (host tree unchanged until commit). |
Use id, path, text as the inputs for this operation.
Write text into the session upper layer (host tree unchanged until commit).
We Load the native plugin required by this operation.
Return [Write text into the session upper layer (host tree unchanged until commit).](sandbox_write(id=id, path=path, text=text)).
read
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| path | any | required | Explicit filesystem path; honor the documented filesystem root and operation effects |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Read through CoW (upper, else lower; whiteout misses). |
Use id, path as the inputs for this operation.
Read through CoW (upper, else lower; whiteout misses).
We Load the native plugin required by this operation.
Return [Read through CoW (upper, else lower; whiteout misses).](sandbox_read(id=id, path=path)).
remove
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| path | any | required | Explicit filesystem path; honor the documented filesystem root and operation effects |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Logical delete (whiteout). |
Use id, path as the inputs for this operation.
Logical delete (whiteout).
We Load the native plugin required by this operation.
Return [Logical delete (whiteout).](sandbox_remove(id=id, path=path)).
diff
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | List of { path, kind } pending changes (write | remove). |
Use id as the inputs for this operation.
List of { path, kind } pending changes (write | remove).
We Load the native plugin required by this operation. Return List of { path, kind } pending changes (write | remove)..
commit
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Apply upper / whiteout to the real workspace root. |
Use id as the inputs for this operation.
Apply upper / whiteout to the real workspace root.
We Load the native plugin required by this operation. Return Apply upper / whiteout to the real workspace root..
discard
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Drop the session without writing the host tree. |
Use id as the inputs for this operation.
Drop the session without writing the host tree.
We Load the native plugin required by this operation. Return Drop the session without writing the host tree..
run
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| source | any | None | Source text inspected or prepared by this operation |
| path | any | None | Explicit filesystem path; honor the documented filesystem root and operation effects |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Run Marqdo under sandbox caps (exec / net / plugin off; fs via CoW). Pass source= or path= (relative to session root). |
Use id, source=None, path=None as the inputs for this operation.
Run Marqdo under sandbox caps (exec / net / plugin off; fs via CoW).
Pass source= or path= (relative to session root).
We Load the native plugin required by this operation.
sourceReturn [Run Marqdo under sandbox caps (exec / net / plugin off; fs via CoW). Pass source= or path= (relative to session root).](sandbox_run(id=id, source=source)).pathReturn [Run Marqdo under sandbox caps (exec / net / plugin off; fs via CoW). Pass source= or path= (relative to session root).](sandbox_run(id=id, path=path)).-
We [Print the prepared message](print(text="ext/ai/sandbox.run: need", source="or", path="")). We End this run with the selected exit status.
inspect_native
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Inspect an existing native CoW session without promoting its writes. |
Use id as the inputs for this operation.
Inspect an existing native CoW session without promoting its writes.
We Load the native plugin required by this operation. Return Inspect an existing native CoW session without promoting its writes..
inspect
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| profile | any | "default" | Capability profile selected for the trial |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | Native caps / change counts, plus the GFM ## profile row under key profile. |
Use id, profile="default" as the inputs for this operation.
Native caps / change counts, plus the GFM ## profile row under key profile.
We retain raw = Inspect native.
We retain prof = Profile.
We retain out = [Set the profile field in the new record](table.put(in=raw, at="profile", value=prof)).
Return out.
report
| 参数 | 类型 | 默认 | 说明 |
|---|---|---|---|
| id | any | required | Identifier produced or selected by the corresponding resource operation |
| path | any | "sandbox-diff.md" | Explicit filesystem path; honor the documented filesystem root and operation effects |
| 返回 | 类型 | 说明 |
|---|---|---|
| result | any | O4: write a markdown review of ## diff for marqdo view / HITL (static report file, not a UI rewrite). |
Use id, path="sandbox-diff.md" as the inputs for this operation.
O4: write a markdown review of ## diff for marqdo view / HITL (static report file, not a UI rewrite).
We retain pending = Diff.
We retain n = Len.
We retain body = "# Sandbox diff report\n\nPending changes: ".
We retain body = body + n.
We retain body = body + "\n\n| path | kind |\n|------|------|\n".
- [row](遍历 pending 为 row)
We retain
p= Read path field). We retaink= Read kind field). We retain body = body + "| ". We retain body = body + p. We retain body = body + " | ". We retain body = body + k. We retain body = body + " |\n". We [Write the prepared text to the selected file](fs.write_text(path=path, text=body)).
**out = **
| path | count |
|---|---|
path |
n |
Return out.