agentengine-sdk-python 0.8.3__py3-none-any.whl → 0.8.5__py3-none-any.whl

ksadk/plugins/builtins.py

@@ -36,6 +36,7 @@ SQLITE_SESSION_STORE_PLUGIN_ID = "io.ksadk.session-store.sqlite"
 WORKSPACE_MCP_PLUGIN_ID = "io.ksadk.mcp.workspace"
 WORKSPACE_SKILL_PLUGIN_ID = "io.ksadk.skill.workspace"
 READ_ONLY_CONTEXT_PLUGIN_ID = "io.ksadk.context.bundle-readonly"
+LOCAL_MEMORY_PROVIDER_PLUGIN_ID = "io.ksadk.memory.local-default"
 CORE_RENDERER_PLUGIN_ID = "io.ksadk.renderer.conversation-core"
 
 SecretResolver = Callable[[str], str | None]
@@ -64,9 +65,7 @@ def _manifest(
                     "domain": "ksadk-platform",
                     "runtime": "python",
                     "entrypoint": "ksadk.plugins.builtins:builtin_capability_factories",
-                    "provides": [
-                        {"definition": definition, "slot": slot, "mode": mode}
-                    ],
+                    "provides": [{"definition": definition, "slot": slot, "mode": mode}],
                     "secretFields": list(secret_fields),
                     "permissions": list(permissions),
                     "isolation": "in-process",
@@ -88,7 +87,7 @@ def _manifest(
 
 
 def builtin_capability_manifests() -> tuple[PluginManifest, ...]:
-    """Return the exact, deterministic Phase 2 built-in capability catalog."""
+    """Return the exact, deterministic Release built-in capability catalog."""
 
     return (
         _manifest(
@@ -120,6 +119,12 @@ def builtin_capability_manifests() -> tuple[PluginManifest, ...]:
             mode="multiple",
             permissions=("filesystem:bundle-read",),
         ),
+        _manifest(
+            LOCAL_MEMORY_PROVIDER_PLUGIN_ID,
+            definition="memory.provider/v1",
+            slot="memory.primary",
+            mode="unique",
+        ),
         _manifest(
             CORE_RENDERER_PLUGIN_ID,
             definition="session.item.renderer/v1",
@@ -129,6 +134,28 @@ def builtin_capability_manifests() -> tuple[PluginManifest, ...]:
     )
 
 
+def builtin_capability_permissions(
+    profile: CompositionProfile,
+) -> frozenset[str]:
+    """Return host-owned permissions for built-ins selected by one Profile.
+
+    Studio's built-in session store, context, renderer, MCP and Skill adapters
+    are part of the trusted PluginHost distribution. Their narrow permissions
+    are granted by that host rather than copied into every user-authored Agent
+    revision. Only exact built-in capability references present in the resolved
+    Profile contribute permissions; AgentProvider permissions remain subject to
+    the Agent's explicit security policy.
+    """
+
+    selected_refs = {capability.ref for capability in profile.capabilities}
+    permissions: set[str] = set()
+    for manifest in builtin_capability_manifests():
+        reference = f"plugin://{manifest.metadata.id}@{manifest.metadata.version}"
+        if reference in selected_refs:
+            permissions.update(manifest.spec.permissions)
+    return frozenset(permissions)
+
+
 class _BuiltinRuntime:
     def __init__(self, plugin_id: str, version: str) -> None:
         self.plugin_id = plugin_id
@@ -242,9 +269,7 @@ class WorkspaceMCPRuntime(_BuiltinRuntime):
             )
         return tuple(inventory)
 
-    def harness_mcp_specs(
-        self, bundle: ResolvedPluginBundle
-    ) -> tuple[McpToolSpec, ...]:
+    def harness_mcp_specs(self, bundle: ResolvedPluginBundle) -> tuple[McpToolSpec, ...]:
         specs: list[McpToolSpec] = []
         for materializer, resolved in self._resources(bundle):
             transport = _required_string(resolved, "transport", code="builtin_mcp_invalid")
@@ -257,6 +282,27 @@ class WorkspaceMCPRuntime(_BuiltinRuntime):
                 resolved, "endpointUrl", code="builtin_mcp_endpoint_missing"
             )
             secret_ref = _optional_string(materializer.get("apiKeyRef"))
+            if secret_ref is None:
+                # 组合器只透传 binding.config；目录资源的凭据声明在合同
+                # envRefs 里（例如 Authorization: env://<API_KEY>）。
+                # materializer 未显式覆盖时回退读取资源自身 envRefs，
+                # 否则 http MCP 少鉴权头必然 401 transport_failed。
+                env_refs = resolved.get("envRefs")
+                if isinstance(env_refs, Mapping) and env_refs:
+                    if len(env_refs) > 1:
+                        raise PluginHostError(
+                            "builtin_mcp_credentials_unsupported",
+                            f"workspace MCP {resolved['name']!r} accepts at most "
+                            "one Authorization credential",
+                        )
+                    header_name, reference = next(iter(env_refs.items()))
+                    if str(header_name).strip().casefold() != "authorization":
+                        raise PluginHostError(
+                            "builtin_mcp_credentials_unsupported",
+                            f"workspace MCP {resolved['name']!r} envRefs header "
+                            f"{header_name!r} is not supported; use Authorization",
+                        )
+                    secret_ref = str(reference).strip()
             api_key: str | None = None
             if secret_ref is not None:
                 if not _is_secret_reference(secret_ref):
@@ -287,9 +333,7 @@ class WorkspaceMCPRuntime(_BuiltinRuntime):
                     url=endpoint,
                     api_key=api_key,
                     tool_filter=tuple(_string_list(materializer.get("toolFilter"))),
-                    tool_name_prefix=_optional_string(
-                        materializer.get("toolNamePrefix")
-                    ),
+                    tool_name_prefix=_optional_string(materializer.get("toolNamePrefix")),
                 )
             )
         return tuple(specs)
@@ -318,13 +362,9 @@ class WorkspaceSkillRuntime(_BuiltinRuntime):
         resolved = _resolved_resources(bundle, "skills")
         contributions: list[HarnessSkillContribution] = []
         for entry in declared:
-            item = _match_resource(
-                entry, resolved, code="builtin_skill_resource_mismatch"
-            )
+            item = _match_resource(entry, resolved, code="builtin_skill_resource_mismatch")
             name = _required_string(item, "name", code="builtin_skill_invalid")
-            bundle_path = _required_string(
-                item, "bundlePath", code="builtin_skill_path_invalid"
-            )
+            bundle_path = _required_string(item, "bundlePath", code="builtin_skill_path_invalid")
             directory = _safe_bundle_path(
                 bundle,
                 bundle_path,
@@ -335,9 +375,7 @@ class WorkspaceSkillRuntime(_BuiltinRuntime):
                 raise PluginHostError(
                     "builtin_skill_path_invalid", f"Skill {name!r} is not a Bundle directory"
                 )
-            expected_digest = _required_string(
-                item, "digest", code="builtin_skill_invalid"
-            )
+            expected_digest = _required_string(item, "digest", code="builtin_skill_invalid")
             if _directory_digest(directory) != expected_digest:
                 raise PluginHostError(
                     "builtin_skill_digest_mismatch",
@@ -347,7 +385,11 @@ class WorkspaceSkillRuntime(_BuiltinRuntime):
                 item, "instructions", code="builtin_skill_instructions_missing"
             )
             contributions.append(
-                HarnessSkillContribution(name=name, instructions=instructions)
+                HarnessSkillContribution(
+                    name=name,
+                    instructions=instructions,
+                    resource_root=directory,
+                )
             )
         if not contributions:
             raise PluginHostError(
@@ -525,12 +567,13 @@ def builtin_capability_factories(
     return {
         SQLITE_SESSION_STORE_PLUGIN_ID: SQLiteSessionStoreFactory(state_root),
         WORKSPACE_MCP_PLUGIN_ID: _WorkspaceMCPFactory(secret_resolver),
-        WORKSPACE_SKILL_PLUGIN_ID: _SimpleFactory(
-            WORKSPACE_SKILL_PLUGIN_ID, WorkspaceSkillRuntime
-        ),
+        WORKSPACE_SKILL_PLUGIN_ID: _SimpleFactory(WORKSPACE_SKILL_PLUGIN_ID, WorkspaceSkillRuntime),
         READ_ONLY_CONTEXT_PLUGIN_ID: _SimpleFactory(
             READ_ONLY_CONTEXT_PLUGIN_ID, ReadOnlyBundleContextRuntime
         ),
+        LOCAL_MEMORY_PROVIDER_PLUGIN_ID: _SimpleFactory(
+            LOCAL_MEMORY_PROVIDER_PLUGIN_ID, _BuiltinRuntime
+        ),
         CORE_RENDERER_PLUGIN_ID: _SimpleFactory(
             CORE_RENDERER_PLUGIN_ID, CoreConversationRendererRuntime
         ),
@@ -538,10 +581,7 @@ def builtin_capability_factories(
 
 
 def _require_manifest(manifest: PluginManifest, plugin_id: str) -> None:
-    if (
-        manifest.metadata.id != plugin_id
-        or manifest.metadata.version != BUILTIN_PLUGIN_VERSION
-    ):
+    if manifest.metadata.id != plugin_id or manifest.metadata.version != BUILTIN_PLUGIN_VERSION:
         raise PluginHostError(
             "builtin_manifest_mismatch",
             f"factory cannot stage {manifest.metadata.id}@{manifest.metadata.version}",
@@ -570,8 +610,7 @@ def _bound_capability_config(
             f"resolved Bundle does not bind built-in capability {plugin_id}@{version}",
         )
     if not any(
-        item.id == plugin_id and item.version == version
-        for item in composition.plugin_lock.plugins
+        item.id == plugin_id and item.version == version for item in composition.plugin_lock.plugins
     ):
         raise PluginHostError(
             "builtin_capability_lock_missing",
@@ -602,9 +641,7 @@ def _resource_entries(
     return tuple(entries)
 
 
-def _resolved_resources(
-    bundle: ResolvedPluginBundle, field: str
-) -> tuple[Mapping[str, Any], ...]:
+def _resolved_resources(bundle: ResolvedPluginBundle, field: str) -> tuple[Mapping[str, Any], ...]:
     capabilities = _mapping(
         bundle.resolved_agent_spec.get("capabilities"),
         code="builtin_bundle_capabilities_missing",
@@ -614,9 +651,7 @@ def _resolved_resources(
         raise PluginHostError(
             "builtin_bundle_capabilities_missing", f"Bundle capabilities.{field} is missing"
         )
-    return tuple(
-        _mapping(item, code="builtin_bundle_capabilities_invalid") for item in raw
-    )
+    return tuple(_mapping(item, code="builtin_bundle_capabilities_invalid") for item in raw)
 
 
 def _match_resource(
@@ -732,6 +767,7 @@ def _is_secret_reference(value: str) -> bool:
 __all__ = [
     "BUILTIN_PLUGIN_VERSION",
     "CORE_RENDERER_PLUGIN_ID",
+    "LOCAL_MEMORY_PROVIDER_PLUGIN_ID",
     "READ_ONLY_CONTEXT_PLUGIN_ID",
     "SQLITE_SESSION_STORE_PLUGIN_ID",
     "WORKSPACE_MCP_PLUGIN_ID",
@@ -744,4 +780,5 @@ __all__ = [
     "WorkspaceSkillRuntime",
     "builtin_capability_factories",
     "builtin_capability_manifests",
+    "builtin_capability_permissions",
 ]

ksadk/plugins/bundle_security.py

@@ -88,7 +88,17 @@ def scan_bundle_security(root: str | Path) -> tuple[BundleSecurityFinding, ...]:
             except json.JSONDecodeError:
                 findings.append(BundleSecurityFinding(relative, "invalid-structured-input"))
                 continue
-            _scan_value(payload, relative, "$", findings)
+            # Skill packages can contain upstream provenance and examples with
+            # historical authoring paths. They are still scanned for literal
+            # credentials and high-confidence tokens, but those reference
+            # paths are not deployment inputs for the Agent.
+            _scan_value(
+                payload,
+                relative,
+                "$",
+                findings,
+                reject_local_paths=not relative.startswith("capabilities/skills/"),
+            )
         elif suffix in {".yaml", ".yml"}:
             # Bundle-owned YAML is a narrow runtime launch declaration.  It
             # has no credential-bearing fields today, but token patterns still
@@ -111,6 +121,8 @@ def _scan_value(
     relative: str,
     field: str,
     findings: list[BundleSecurityFinding],
+    *,
+    reject_local_paths: bool,
 ) -> None:
     if isinstance(value, dict):
         for key, child in value.items():
@@ -124,11 +136,23 @@ def _scan_value(
                 findings.append(
                     BundleSecurityFinding(relative, "literal-secret-field", child_field)
                 )
-            _scan_value(child, relative, child_field, findings)
+            _scan_value(
+                child,
+                relative,
+                child_field,
+                findings,
+                reject_local_paths=reject_local_paths,
+            )
         return
     if isinstance(value, list):
         for index, child in enumerate(value):
-            _scan_value(child, relative, f"{field}[{index}]", findings)
+            _scan_value(
+                child,
+                relative,
+                f"{field}[{index}]",
+                findings,
+                reject_local_paths=reject_local_paths,
+            )
         return
     if isinstance(value, str):
         _scan_text(value, relative, findings, field=field)
@@ -139,7 +163,7 @@ def _scan_value(
             split.username is not None or split.password is not None
         ):
             findings.append(BundleSecurityFinding(relative, "url-credentials", field))
-        if value.startswith(("/Users/", "/home/", "C:\\Users\\")):
+        if reject_local_paths and value.startswith(("/Users/", "/home/", "C:\\Users\\")):
             findings.append(BundleSecurityFinding(relative, "local-home-path", field))