maf-sandbox-codeact 0.2.2__tar.gz → 0.3.0__tar.gz

{maf_sandbox_codeact-0.2.2 → maf_sandbox_codeact-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: maf-sandbox-codeact
-Version: 0.2.2
+Version: 0.3.0
 Summary: CodeAct as a Microsoft Agent Framework tool — the model writes a short Python program and it runs inside a sandbox — written against maf-sandbox so it runs on any sandbox backend.
 Keywords: codeact,code-execution,sandbox,agent-framework,microsoft-agent-framework
 Author: SOKOLAI BV
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Interpreters
-Requires-Dist: maf-sandbox>=0.8.0,<0.11
+Requires-Dist: maf-sandbox>=0.11.0,<0.13
 Requires-Dist: agent-framework-core>=1.13.0,<2
 Requires-Python: >=3.12, <3.15
 Project-URL: Homepage, https://www.sokol.ai
@@ -60,20 +60,20 @@ Pass `router=None` — or a router with no backend — and you get `[]` back: an
 
 One tool, `execute_code`. The program is written to a directory of its own and run as the argv `["python3", ".../program.py"]`, and the result is its stdout, its stderr when it wrote any, and its exit code when that was not zero. There is no REPL echo, so a program that computes without printing returns a sentence saying so.
 
-**Every call gets a fresh directory, and that is load-bearing rather than hygiene.** `acquire` is get-or-create, so the same sandbox serves every call in a conversation. Without a per-call directory a file deleted from the workspace between rounds would still be there for the next program to read as current, and last round's output file would be collected as this round's — a stale answer presented as a live one, in a kind whose whole job is transforming files.
+**Every call gets a fresh directory, and that is load-bearing rather than hygiene.** `acquire` is get-or-create, so the same sandbox serves every call in a conversation. Without a per-call directory a file deleted from the file store between rounds would still be there for the next program to read as current, and last round's output file would be collected as this round's — a stale answer presented as a live one, in a kind whose whole job is transforming files.
 
 Two further channels exist and neither is on by default. Wire neither and this is the stdout-only kind it has always been.
 
 ### Files in
 
-Pass a `workspace_store` and the tool grows a `files` parameter:
+Pass a `file_store` and the tool grows a `files` parameter:
 
 ```python
 tools = make_codeact_tools(router, "data-analyst", context,
-                           workspace_store=store, image=...)
+                           file_store=store, image=...)
 ```
 
-Each named file is read from the store and written into the program's working directory under its own name, so `data/sales.csv` is what the program opens. **The caller's listing is the authority**: only a name present in `WorkspaceContext.list_files` is ever shared, so a name the model invented — or read out of a file it was given — has nowhere to go. A name outside the listing comes back as a refusal naming the near misses; a name that traverses comes back as a refusal that echoes nothing.
+Each named file is read from the store and written into the program's working directory under its own name, so `data/sales.csv` is what the program opens. **The caller's listing is the authority**: only a name present in `CallerContext.list_files` is ever shared, so a name the model invented — or read out of a file it was given — has nowhere to go. A name outside the listing comes back as a refusal naming the near misses; a name that traverses comes back as a refusal that echoes nothing.
 
 ### Files out
 
@@ -103,11 +103,17 @@ Either way the kind requires `FILES_OUT` and **never** `FILES_LIST`: it collects
 
 **Nothing is dispatchable from inside.** There is no host-tool registry in this version, and that emptiness is the security story rather than a missing feature: the program cannot open a socket and cannot call a host function, so it initiates nothing. The output sink does not change that — the kind calls it host-side, after the program has exited, and nothing inside the sandbox can reach it. A host wanting a hard stop denies `FILES_OUT`.
 
-**A workspace store is ingress, and it is the host's own.** "Nothing can get in" describes what the *program* can initiate, not what the host puts there. With `workspace_store` wired, caller-selected files are written into the sandbox before the program runs — deliberately, and constrained to the caller's listing, so the model cannot widen the set. What that content *is* remains the host's to know: a workspace file may itself carry text from somewhere untrusted, and a program that parses it is running on input the sandbox did not vet. Wire no store and this paragraph does not apply.
+**A file store is ingress, and it is the host's own.** "Nothing can get in" describes what the *program* can initiate, not what the host puts there. With `file_store` wired, caller-selected files are written into the sandbox before the program runs — deliberately, and constrained to the caller's listing, so the model cannot widen the set. What that content *is* remains the host's to know: a file in the store may itself carry text from somewhere untrusted, and a program that parses it is running on input the sandbox did not vet. Wire no store and this paragraph does not apply.
 
 **The tool declares no `source_integrity`.** The library's default is `"trusted"`, which is right for a workload whose result is a compiler's own diagnostics and wrong for this one: what comes back is whatever a model-written `print(...)` chose to emit. Undeclared, MAF's information-flow tracker applies its untrusted default and the result taints the conversation — the fail-safe direction, and the honest one.
 
-**Isolation is the host's call, and a store changes what that call is about.** This kind does not raise `SandboxSpec.min_isolation`, so the router's floor governs — `MICROVM` unless the host opted down. A kind that ran code influenced by untrusted external content would pin the floor itself, and this one cannot know whether it is one: with no store, the program's only input is source the model wrote, and opting down to `CONTAINER` weighs model-written code against a shared kernel. **With a store, the program also reads whatever those files contain**, so the floor should be chosen against the provenance of the workspace, not against this kind's defaults. Only the host knows that.
+**Isolation is the host's call, and a store changes what that call is about.** This kind does not raise `SandboxSpec.min_isolation`, so the router's floor governs — `MICROVM` unless the host opted down. A kind that ran code influenced by untrusted external content would pin the floor itself, and this one cannot know whether it is one: with no store, the program's only input is source the model wrote, and opting down to `CONTAINER` weighs model-written code against a shared kernel. **With a store, the program also reads whatever those files contain**, so the floor should be chosen against the provenance of the file store, not against this kind's defaults. Only the host knows that.
+
+## Upgrading to 0.3
+
+`0.3.0` follows `maf-sandbox` 0.11, which retired the word `workspace` from the vocabulary. It requires that release.
+
+**`make_codeact_tools` takes `file_store` where it took `workspace_store`.** This one is **keyword-only**, so unlike the Bicep kind's there is no positional call that survives untouched: every host wiring a store has an edit to make. A host that wires none is unaffected, since the parameter defaults to `None`.
 
 ## What this version is not
 

{maf_sandbox_codeact-0.2.2 → maf_sandbox_codeact-0.3.0}/README.md

@@ -35,20 +35,20 @@ Pass `router=None` — or a router with no backend — and you get `[]` back: an
 
 One tool, `execute_code`. The program is written to a directory of its own and run as the argv `["python3", ".../program.py"]`, and the result is its stdout, its stderr when it wrote any, and its exit code when that was not zero. There is no REPL echo, so a program that computes without printing returns a sentence saying so.
 
-**Every call gets a fresh directory, and that is load-bearing rather than hygiene.** `acquire` is get-or-create, so the same sandbox serves every call in a conversation. Without a per-call directory a file deleted from the workspace between rounds would still be there for the next program to read as current, and last round's output file would be collected as this round's — a stale answer presented as a live one, in a kind whose whole job is transforming files.
+**Every call gets a fresh directory, and that is load-bearing rather than hygiene.** `acquire` is get-or-create, so the same sandbox serves every call in a conversation. Without a per-call directory a file deleted from the file store between rounds would still be there for the next program to read as current, and last round's output file would be collected as this round's — a stale answer presented as a live one, in a kind whose whole job is transforming files.
 
 Two further channels exist and neither is on by default. Wire neither and this is the stdout-only kind it has always been.
 
 ### Files in
 
-Pass a `workspace_store` and the tool grows a `files` parameter:
+Pass a `file_store` and the tool grows a `files` parameter:
 
 ```python
 tools = make_codeact_tools(router, "data-analyst", context,
-                           workspace_store=store, image=...)
+                           file_store=store, image=...)
 ```
 
-Each named file is read from the store and written into the program's working directory under its own name, so `data/sales.csv` is what the program opens. **The caller's listing is the authority**: only a name present in `WorkspaceContext.list_files` is ever shared, so a name the model invented — or read out of a file it was given — has nowhere to go. A name outside the listing comes back as a refusal naming the near misses; a name that traverses comes back as a refusal that echoes nothing.
+Each named file is read from the store and written into the program's working directory under its own name, so `data/sales.csv` is what the program opens. **The caller's listing is the authority**: only a name present in `CallerContext.list_files` is ever shared, so a name the model invented — or read out of a file it was given — has nowhere to go. A name outside the listing comes back as a refusal naming the near misses; a name that traverses comes back as a refusal that echoes nothing.
 
 ### Files out
 
@@ -78,11 +78,17 @@ Either way the kind requires `FILES_OUT` and **never** `FILES_LIST`: it collects
 
 **Nothing is dispatchable from inside.** There is no host-tool registry in this version, and that emptiness is the security story rather than a missing feature: the program cannot open a socket and cannot call a host function, so it initiates nothing. The output sink does not change that — the kind calls it host-side, after the program has exited, and nothing inside the sandbox can reach it. A host wanting a hard stop denies `FILES_OUT`.
 
-**A workspace store is ingress, and it is the host's own.** "Nothing can get in" describes what the *program* can initiate, not what the host puts there. With `workspace_store` wired, caller-selected files are written into the sandbox before the program runs — deliberately, and constrained to the caller's listing, so the model cannot widen the set. What that content *is* remains the host's to know: a workspace file may itself carry text from somewhere untrusted, and a program that parses it is running on input the sandbox did not vet. Wire no store and this paragraph does not apply.
+**A file store is ingress, and it is the host's own.** "Nothing can get in" describes what the *program* can initiate, not what the host puts there. With `file_store` wired, caller-selected files are written into the sandbox before the program runs — deliberately, and constrained to the caller's listing, so the model cannot widen the set. What that content *is* remains the host's to know: a file in the store may itself carry text from somewhere untrusted, and a program that parses it is running on input the sandbox did not vet. Wire no store and this paragraph does not apply.
 
 **The tool declares no `source_integrity`.** The library's default is `"trusted"`, which is right for a workload whose result is a compiler's own diagnostics and wrong for this one: what comes back is whatever a model-written `print(...)` chose to emit. Undeclared, MAF's information-flow tracker applies its untrusted default and the result taints the conversation — the fail-safe direction, and the honest one.
 
-**Isolation is the host's call, and a store changes what that call is about.** This kind does not raise `SandboxSpec.min_isolation`, so the router's floor governs — `MICROVM` unless the host opted down. A kind that ran code influenced by untrusted external content would pin the floor itself, and this one cannot know whether it is one: with no store, the program's only input is source the model wrote, and opting down to `CONTAINER` weighs model-written code against a shared kernel. **With a store, the program also reads whatever those files contain**, so the floor should be chosen against the provenance of the workspace, not against this kind's defaults. Only the host knows that.
+**Isolation is the host's call, and a store changes what that call is about.** This kind does not raise `SandboxSpec.min_isolation`, so the router's floor governs — `MICROVM` unless the host opted down. A kind that ran code influenced by untrusted external content would pin the floor itself, and this one cannot know whether it is one: with no store, the program's only input is source the model wrote, and opting down to `CONTAINER` weighs model-written code against a shared kernel. **With a store, the program also reads whatever those files contain**, so the floor should be chosen against the provenance of the file store, not against this kind's defaults. Only the host knows that.
+
+## Upgrading to 0.3
+
+`0.3.0` follows `maf-sandbox` 0.11, which retired the word `workspace` from the vocabulary. It requires that release.
+
+**`make_codeact_tools` takes `file_store` where it took `workspace_store`.** This one is **keyword-only**, so unlike the Bicep kind's there is no positional call that survives untouched: every host wiring a store has an edit to make. A host that wires none is unaffected, since the parameter defaults to `None`.
 
 ## What this version is not
 

{maf_sandbox_codeact-0.2.2 → maf_sandbox_codeact-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "maf-sandbox-codeact"
-version = "0.2.2"
+version = "0.3.0"
 description = "CodeAct as a Microsoft Agent Framework tool — the model writes a short Python program and it runs inside a sandbox — written against maf-sandbox so it runs on any sandbox backend."
 readme = "README.md"
 requires-python = ">=3.12,<3.15"
@@ -24,7 +24,7 @@ classifiers = [
     "Topic :: Software Development :: Interpreters",
 ]
 dependencies = [
-    "maf-sandbox>=0.8.0,<0.11",
+    "maf-sandbox>=0.11.0,<0.13",
     "agent-framework-core>=1.13.0,<2",
 ]
 

{maf_sandbox_codeact-0.2.2 → maf_sandbox_codeact-0.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "maf-sandbox-codeact"
-version = "0.2.2"
+version = "0.3.0"
 description = "CodeAct as a Microsoft Agent Framework tool — the model writes a short Python program and it runs inside a sandbox — written against maf-sandbox so it runs on any sandbox backend."
 readme = "README.md"
 requires-python = ">=3.12,<3.15"
@@ -34,7 +34,7 @@ dependencies = [
     # published wheel resolves a maf-sandbox base missing those imports. The number itself is
     # below, and `scripts/set_dependents_range.py` moves it — so this says which release the
     # floor is for, never which release that is.
-    "maf-sandbox>=0.8.0,<0.11",
+    "maf-sandbox>=0.11.0,<0.13",
     # The `@tool` decorator. MAF is a genuine dependency of the tool itself, not of the host
     # application.
     "agent-framework-core>=1.13.0,<2",

{maf_sandbox_codeact-0.2.2 → maf_sandbox_codeact-0.3.0}/src/maf_sandbox_codeact/_tool.py

@@ -9,7 +9,7 @@ pull surface, so the same tool runs unchanged against ACA Sandboxes, a Docker co
 in-process fake.
 
 Three channels, and the host chooses which of them exist.  Stdout is always there.  A
-**workspace store** adds a ``files`` parameter, so a program can transform files that already
+**file store** adds a ``files`` parameter, so a program can transform files that already
 exist rather than only data the model wrote into its own source.  An **output sink** plus a
 :class:`CodeactOutputs` mode adds a way for files the program produces to reach host state.
 Wire neither and this is the stdout-only kind it has always been, with nothing dispatchable
@@ -28,6 +28,7 @@ from uuid import uuid4
 
 from maf_sandbox import (
     DEFAULT_TRANSFER_LIMITS,
+    CallerContext,
     Capability,
     DeclaredOutput,
     ExecResult,
@@ -38,7 +39,6 @@ from maf_sandbox import (
     SandboxRouter,
     SandboxSpec,
     TransferLimits,
-    WorkspaceContext,
     collect_outputs,
     error_detail,
     validate_artifact_name,
@@ -159,9 +159,9 @@ def codeact_sandbox_spec(
 def make_codeact_tools(
     router: SandboxRouter | None,
     agent_dir: str,
-    context: WorkspaceContext,
+    context: CallerContext,
     *,
-    workspace_store: "AgentFileStore | None" = None,
+    file_store: "AgentFileStore | None" = None,
     output_sink: OutputSink | None = None,
     outputs: CodeactOutputs = CodeactOutputs.NONE,
     outbound_max_confidentiality: str | None = None,
@@ -174,15 +174,15 @@ def make_codeact_tools(
     """Return the ``[execute_code]`` tool list, or ``[]`` when no sandbox is available.
 
     The tool's *signature* follows the channels the host wired: ``files`` appears only with a
-    ``workspace_store``, and ``outputs`` only under :data:`CodeactOutputs.DECLARED`.  A model is
+    ``file_store``, and ``outputs`` only under :data:`CodeactOutputs.DECLARED`.  A model is
     never shown a parameter this deployment cannot honour.
 
     Args:
         router: The sandbox router, or ``None`` when sandboxing is not configured.
         agent_dir: The agent's directory name. Baked into the sandbox key at factory time
             rather than taken from the model at call time.
-        context: How to read the caller's scope and thread, and how to enumerate the workspace.
-        workspace_store: The agent's workspace store. Given one, the tool takes a ``files``
+        context: How to read the caller's scope and thread, and how to enumerate the file store.
+        file_store: The agent's file store. Given one, the tool takes a ``files``
             parameter and shares those files into the sandbox; the caller's listing is the
             authority on which names exist, exactly as it is for the Bicep kind.
         output_sink: Where produced files land. Required by any mode but
@@ -255,7 +255,7 @@ def make_codeact_tools(
         image, image_id, outputs=outputs, files_in=files_in, files_out=files_out
     )
     return sandboxed_tool(
-        lambda session: _execute_code_tool(session, workspace_store, outputs, exec_timeout_seconds),
+        lambda session: _execute_code_tool(session, file_store, outputs, exec_timeout_seconds),
         router=router,
         context=context,
         agent_dir=agent_dir,
@@ -322,8 +322,8 @@ _DESCRIPTION_MANIFEST = f"""**To produce files, write them into the working dire
 _DESCRIPTION_ARG_CODE = """code: The Python source to run.  The standard library, plus
                 whatever the sandbox image ships."""
 
-_DESCRIPTION_ARG_FILES = """files: Workspace-relative paths to share into the sandbox, or
-                omit for none.  Only files in your workspace listing can be shared."""
+_DESCRIPTION_ARG_FILES = """files: Store-relative paths to share into the sandbox, or
+                omit for none.  Only files in your file store listing can be shared."""
 
 _DESCRIPTION_ARG_OUTPUTS = """outputs: The file names your program will write into its
                 working directory, or omit if it writes none."""
@@ -369,7 +369,7 @@ def _execute_code_tool(
     """Build the ``execute_code`` body for one attached tool.
 
     Four signatures over one implementation, because MAF derives the tool's schema from the
-    function's parameters: a host that wired no workspace store must not be shown ``files``.
+    function's parameters: a host that wired no file store must not be shown ``files``.
     """
 
     async def run(code: str, files: list[str] | None, declared: list[str] | None) -> str:
@@ -455,10 +455,10 @@ async def _execute(
     if over_cap is not None:
         return over_cap
     if store is not None:
-        resolved = await _resolve_workspace_files(session, store, files, reserved=reserved)
+        resolved = await _resolve_listed_files(session, store, files, reserved=reserved)
         if isinstance(resolved, str):
             return resolved
-        read = await _read_workspace_files(store, resolved, tally)
+        read = await _read_listed_files(store, resolved, tally)
         if isinstance(read, str):
             return read
         shared = read
@@ -513,7 +513,7 @@ async def _execute(
 # --- Files in ------------------------------------------------------------------------------
 
 
-async def _resolve_workspace_files(
+async def _resolve_listed_files(
     session: SandboxToolSession,
     store: "AgentFileStore",
     files: list[str],
@@ -553,7 +553,7 @@ async def _resolve_workspace_files(
             return f"Error: {name!r} was listed twice."
         if name not in known:
             logger.warning(
-                "execute_code: %r is not in this tool's workspace listing (%d file(s) visible) "
+                "execute_code: %r is not in this tool's file store listing (%d file(s) visible) "
                 "— the store wired here may be narrower than the agent's",
                 name,
                 len(listing),
@@ -566,7 +566,7 @@ async def _resolve_workspace_files(
     return resolved
 
 
-#: Capped so a large workspace cannot flood the model's context.
+#: Capped so a large file store cannot flood the model's context.
 _LISTING_HINT_MAX = 20
 
 
@@ -582,7 +582,7 @@ def _listing_hint(name: str, listing: list[str]) -> str:
     return f"Files visible here: {', '.join(shown)}{more}."
 
 
-async def _read_workspace_files(
+async def _read_listed_files(
     store: "AgentFileStore", names: list[str], tally: "_InboundTally"
 ) -> list[tuple[str, str]] | str:
     """Read every requested file into memory, or answer with the refusal.
@@ -601,14 +601,14 @@ async def _read_workspace_files(
         try:
             content = await store.read(name)
         except Exception as exc:  # noqa: BLE001
-            logger.warning("execute_code: could not read %r from workspace: %s", name, exc)
-            return f"Error: could not read {name!r} from workspace"
+            logger.warning("execute_code: could not read %r from the file store: %s", name, exc)
+            return f"Error: could not read {name!r} from the file store"
         if content is None:
             # A store read can miss without raising (the file was listed, then removed). Writing
             # `None` through would put the string "None" into the sandbox for the program to
             # parse.
             logger.warning("execute_code: %r is listed but has no content", name)
-            return f"Error: {name!r} is listed in the workspace but has no content"
+            return f"Error: {name!r} is listed in the file store but has no content"
         over_cap = tally.add(name, content)
         if over_cap is not None:
             return over_cap
@@ -677,7 +677,7 @@ class _InboundTally:
 
 
 async def _write_shared(sandbox: "Sandbox", name: str, guest_path: str, content: str) -> str | None:
-    """Put one already-read workspace file into the run's directory, or answer with the refusal."""
+    """Put one already-read file store file into the run's directory, or answer with the refusal."""
     try:
         await sandbox.write_file(guest_path, content)
     except Exception as exc:  # noqa: BLE001