Files
marqdo/ext/ai/sandbox.mq.md

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).
plugin sys table fs
lib/plugin.mq.md lib/sys.mq.md lib/table.mq.md lib/fs.mq.md

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.

  1. p We Load the native plugin required by this operation.

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
  1. 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.

  1. root Return 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.

  1. source Return [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)).
  2. path Return [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 retain k = 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.