agentengine-sdk-python 0.8.2__py3-none-any.whl → 0.8.4__py3-none-any.whl

ksadk/plugins/kernel_adapter.py

@@ -0,0 +1,205 @@
+"""Provider-neutral AgentKernel adapter for PluginHost runtimes."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from ksadk.kernel.contracts import InjectPayload, SteerPayload
+from ksadk.kernel.errors import UnsupportedControlError
+from ksadk.runtime import (
+    BaseRuntime,
+    CancelResult,
+    CheckpointDescriptor,
+    PauseResult,
+    ResumePayload,
+    ResumeTarget,
+    RunHandle,
+    RuntimeAdapter,
+    StartRequest,
+)
+
+BindDelegate = Callable[[str], Awaitable[RuntimeAdapter]]
+ReleaseBinding = Callable[[str], Awaitable[None]]
+
+_PROVIDER_RUNTIME_TYPE_KEY = "_ksadk_plugin_provider_runtime_type"
+
+
+class _PluginKernelRuntime(BaseRuntime):
+    def __init__(self, runtime_type: str) -> None:
+        self.runtime_type = runtime_type
+
+    def native_capabilities(self) -> dict[str, Any]:
+        return {
+            "provider_owned": True,
+            "runtime_adapter": True,
+            "session_continuity": {"durable": False, "scope": "process"},
+        }
+
+
+class PluginKernelAdapter(RuntimeAdapter):
+    """Expose a lazily activated Agent Provider through the Kernel contract."""
+
+    def __init__(
+        self,
+        *,
+        runtime_type: str,
+        bind_delegate: BindDelegate,
+        release_binding: ReleaseBinding,
+    ) -> None:
+        super().__init__(_PluginKernelRuntime(runtime_type))
+        self._runtime_type = runtime_type
+        self._bind_delegate_callback = bind_delegate
+        self._release_binding_callback = release_binding
+        self._delegate: RuntimeAdapter | None = None
+        self._native_handle: RunHandle | None = None
+
+    async def start(self, request: StartRequest) -> RunHandle:
+        try:
+            delegate = await self._bind_delegate(request.session_id)
+            metadata = dict(request.metadata)
+            if not metadata.get("invocation_id") and metadata.get("run_id"):
+                metadata["invocation_id"] = metadata["run_id"]
+            native_handle = await delegate.start(
+                request.model_copy(update={"metadata": metadata})
+            )
+            self._native_handle = native_handle
+            return self._outer_handle(native_handle)
+        except BaseException:
+            await self._release_failed_binding(request.session_id)
+            raise
+
+    def stream(self, handle: RunHandle):  # type: ignore[no-untyped-def]
+        return self._require_delegate().stream(self._provider_handle(handle))
+
+    async def cancel(self, handle: RunHandle) -> CancelResult:
+        return await self._require_delegate().cancel(self._provider_handle(handle))
+
+    async def pause(self, handle: RunHandle) -> PauseResult:
+        return await self._require_delegate().pause(self._provider_handle(handle))
+
+    async def submit(self, handle: RunHandle, payload: ResumePayload) -> None:
+        await self._require_delegate().submit(self._provider_handle(handle), payload)
+
+    async def resume(
+        self,
+        handle: RunHandle,
+        target: ResumeTarget,
+        payload: ResumePayload | None,
+    ) -> RunHandle:
+        native_handle = await self._require_delegate().resume(
+            self._provider_handle(handle), target, payload
+        )
+        self._native_handle = native_handle
+        return self._outer_handle(native_handle)
+
+    async def attach(self, handle: RunHandle) -> RunHandle:
+        try:
+            delegate = await self._bind_delegate(handle.session_id)
+            native_handle = await delegate.attach(self._provider_handle(handle))
+            self._native_handle = native_handle
+            return self._outer_handle(native_handle)
+        except BaseException:
+            await self._release_failed_binding(handle.session_id)
+            raise
+
+    async def steer(self, handle: RunHandle, payload: SteerPayload) -> None:
+        await self._require_delegate().steer(self._provider_handle(handle), payload)
+
+    async def inject(self, handle: RunHandle, payload: InjectPayload) -> None:
+        await self._require_delegate().inject(self._provider_handle(handle), payload)
+
+    async def checkpoint(self, handle: RunHandle) -> CheckpointDescriptor:
+        return await self._require_delegate().checkpoint(self._provider_handle(handle))
+
+    async def durable_restore(self, handle: RunHandle) -> RunHandle:
+        try:
+            delegate = await self._bind_delegate(handle.session_id)
+            native_handle = await delegate.durable_restore(
+                self._provider_handle(handle)
+            )
+            self._native_handle = native_handle
+            return self._outer_handle(native_handle)
+        except BaseException:
+            await self._release_failed_binding(handle.session_id)
+            raise
+
+    def is_handle_attached(self, handle: RunHandle) -> bool:
+        return self._delegate is not None and self._delegate.is_handle_attached(
+            self._provider_handle(handle)
+        )
+
+    async def close(self, handle: RunHandle) -> None:
+        try:
+            await self._require_delegate().close(self._provider_handle(handle))
+        finally:
+            await self._release_binding_callback(handle.session_id)
+
+    def capabilities(self):  # type: ignore[no-untyped-def]
+        # Provider activation is asynchronous, so admission is deliberately
+        # conservative until a session has bound its delegate.
+        if self._delegate is None:
+            return super().capabilities()
+        return self._delegate.capabilities()
+
+    def _require_delegate(self) -> RuntimeAdapter:
+        if self._delegate is None:
+            raise UnsupportedControlError(
+                "PluginHost RuntimeAdapter has not started a provider activation"
+            )
+        return self._delegate
+
+    async def _bind_delegate(self, session_id: str) -> RuntimeAdapter:
+        delegate = await self._bind_delegate_callback(session_id)
+        if not isinstance(delegate, RuntimeAdapter):
+            raise RuntimeError("AgentProvider returned an invalid RuntimeAdapter")
+        self._delegate = delegate
+        return delegate
+
+    def _outer_handle(self, handle: RunHandle) -> RunHandle:
+        native_ref = dict(handle.native_ref)
+        native_ref[_PROVIDER_RUNTIME_TYPE_KEY] = handle.runtime_type
+        return handle.model_copy(
+            update={"runtime_type": self._runtime_type, "native_ref": native_ref}
+        )
+
+    def _provider_handle(self, handle: RunHandle) -> RunHandle:
+        cached = self._native_handle
+        if (
+            cached is not None
+            and cached.run_id == handle.run_id
+            and cached.session_id == handle.session_id
+        ):
+            return cached
+        native_ref = dict(handle.native_ref)
+        runtime_type = str(native_ref.pop(_PROVIDER_RUNTIME_TYPE_KEY, "")).strip()
+        if not runtime_type:
+            runtime_type = self._require_delegate().runtime.runtime_type
+        return handle.model_copy(
+            update={"runtime_type": runtime_type, "native_ref": native_ref}
+        )
+
+    async def _release_failed_binding(self, session_id: str) -> None:
+        """Close a partially opened activation even under cancellation."""
+
+        self._delegate = None
+        self._native_handle = None
+        cleanup = asyncio.create_task(self._release_binding_callback(session_id))
+        interrupted = False
+        while not cleanup.done():
+            try:
+                await asyncio.shield(cleanup)
+            except asyncio.CancelledError:
+                interrupted = True
+        try:
+            cleanup.result()
+        except Exception:
+            # Preserve the provider/delegate failure. Its owner still gets the
+            # terminal suspend path for disposing a host that could not close.
+            pass
+        if interrupted:
+            raise asyncio.CancelledError
+
+
+__all__ = ["BindDelegate", "PluginKernelAdapter", "ReleaseBinding"]

ksadk/plugins/providers/__init__.py

@@ -0,0 +1,108 @@
+"""Public Provider index without eagerly starting optional runtimes.
+
+The catalog must remain usable in a base install.  ADK-backed Harness code is
+loaded only when a caller actually asks for a Harness-specific symbol.
+"""
+
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+
+_EXPORTS = {
+    "BUILTIN_PROVIDER_VERSION": ("legacy_catalog", "BUILTIN_PROVIDER_VERSION"),
+    "CODEX_AGENT_PROVIDER_PLUGIN_ID": ("legacy_catalog", "CODEX_AGENT_PROVIDER_PLUGIN_ID"),
+    "KSADK_HARNESS_AGENT_PROVIDER_PLUGIN_ID": (
+        "legacy_catalog",
+        "KSADK_HARNESS_AGENT_PROVIDER_PLUGIN_ID",
+    ),
+    "builtin_agent_provider_manifests": ("legacy_catalog", "builtin_agent_provider_manifests"),
+    "legacy_harness_agent_provider_manifest": (
+        "legacy_catalog",
+        "legacy_harness_agent_provider_manifest",
+    ),
+    "CodexAgentProviderFactory": ("codex", "CodexAgentProviderFactory"),
+    "CodexAgentProviderRuntime": ("codex", "CodexAgentProviderRuntime"),
+    "CodexProviderInventory": ("codex", "CodexProviderInventory"),
+    "CodexTurnRequest": ("codex", "CodexTurnRequest"),
+    "CodexTurnResult": ("codex", "CodexTurnResult"),
+    "SHIPPED_CODEX_DSH_PACKAGE": ("codex_dsh", "SHIPPED_CODEX_DSH_PACKAGE"),
+    "SHIPPED_CODEX_PROVIDER_ID": ("codex_dsh", "SHIPPED_CODEX_PROVIDER_ID"),
+    "SHIPPED_CODEX_PROVIDER_VERSION": ("codex_dsh", "SHIPPED_CODEX_PROVIDER_VERSION"),
+    "KsADKCodexDshBridgeFactory": ("codex_dsh", "KsADKCodexDshBridgeFactory"),
+    "KsADKCodexDshBridgeRuntime": ("codex_dsh", "KsADKCodexDshBridgeRuntime"),
+    "ShippedCodexDshBundle": ("codex_dsh", "ShippedCodexDshBundle"),
+    "shipped_codex_dsh_bundle": ("codex_dsh", "shipped_codex_dsh_bundle"),
+    "shipped_codex_dsh_host_command": ("codex_dsh", "shipped_codex_dsh_host_command"),
+    "DSH_AGENT_PROVIDER_HOST_METHODS": ("dsh", "DSH_AGENT_PROVIDER_HOST_METHODS"),
+    "DSH_AGENT_PROVIDER_HOST_PROTOCOL": ("dsh", "DSH_AGENT_PROVIDER_HOST_PROTOCOL"),
+    "DSH_HOST_USER_PERMISSION": ("dsh", "DSH_HOST_USER_PERMISSION"),
+    "DshAgentProviderDescriptor": ("dsh", "DshAgentProviderDescriptor"),
+    "DshAgentProviderFactory": ("dsh", "DshAgentProviderFactory"),
+    "DshAgentProviderHost": ("dsh", "DshAgentProviderHost"),
+    "DshAgentProviderInventory": ("dsh", "DshAgentProviderInventory"),
+    "DshAgentProviderPreflight": ("dsh", "DshAgentProviderPreflight"),
+    "DshAgentProviderRegistration": ("dsh", "DshAgentProviderRegistration"),
+    "DshAgentProviderRuntime": ("dsh", "DshAgentProviderRuntime"),
+    "DshPreparedAgent": ("dsh", "DshPreparedAgent"),
+    "dsh_agent_provider_manifest": ("dsh", "dsh_agent_provider_manifest"),
+    "DSH_CAPABILITY_BUNDLE_PACKAGE": (
+        "dsh_capabilities",
+        "DSH_CAPABILITY_BUNDLE_PACKAGE",
+    ),
+    "DSH_CAPABILITY_HOST_PROTOCOL": ("dsh_capabilities", "DSH_CAPABILITY_HOST_PROTOCOL"),
+    "DSH_CAPABILITY_HOST_VERSION": ("dsh_capabilities", "DSH_CAPABILITY_HOST_VERSION"),
+    "DshCapabilityTool": ("dsh_capabilities", "DshCapabilityTool"),
+    "DshMcpConnectorLease": ("dsh_capabilities", "DshMcpConnectorLease"),
+    "DshProfileCapabilityDescriptor": (
+        "dsh_capabilities",
+        "DshProfileCapabilityDescriptor",
+    ),
+    "DshProfileCapabilityHost": ("dsh_capabilities", "DshProfileCapabilityHost"),
+    "DshProfileCapabilityInventory": (
+        "dsh_capabilities",
+        "DshProfileCapabilityInventory",
+    ),
+    "load_dsh_capability_bundle": ("dsh_capabilities", "load_dsh_capability_bundle"),
+    "DSH_PROFILE_MCP_PLUGIN_ID": ("dsh_mcp", "DSH_PROFILE_MCP_PLUGIN_ID"),
+    "DSH_PROFILE_MCP_PLUGIN_VERSION": ("dsh_mcp", "DSH_PROFILE_MCP_PLUGIN_VERSION"),
+    "DshProfileMCPFactory": ("dsh_mcp", "DshProfileMCPFactory"),
+    "DshProfileMCPRuntime": ("dsh_mcp", "DshProfileMCPRuntime"),
+    "dsh_profile_mcp_manifest": ("dsh_mcp", "dsh_profile_mcp_manifest"),
+    "HarnessContextSource": ("harness", "HarnessContextSource"),
+    "HarnessMCPSource": ("harness", "HarnessMCPSource"),
+    "HarnessProviderInventory": ("harness", "HarnessProviderInventory"),
+    "HarnessSkillContribution": ("harness", "HarnessSkillContribution"),
+    "HarnessSkillSource": ("harness", "HarnessSkillSource"),
+    "HarnessTurnRequest": ("harness", "HarnessTurnRequest"),
+    "HarnessTurnResult": ("harness", "HarnessTurnResult"),
+    "KsADKHarnessProviderFactory": ("harness", "KsADKHarnessProviderFactory"),
+    "KsADKHarnessProviderRuntime": ("harness", "KsADKHarnessProviderRuntime"),
+    "SHIPPED_HARNESS_DSH_PACKAGE": ("harness_dsh", "SHIPPED_HARNESS_DSH_PACKAGE"),
+    "KsADKHarnessDshBridgeFactory": ("harness_dsh", "KsADKHarnessDshBridgeFactory"),
+    "KsADKHarnessDshBridgeRuntime": ("harness_dsh", "KsADKHarnessDshBridgeRuntime"),
+    "ShippedHarnessDshBundle": ("harness_dsh", "ShippedHarnessDshBundle"),
+    "shipped_harness_dsh_bundle": ("harness_dsh", "shipped_harness_dsh_bundle"),
+    "shipped_harness_dsh_host_command": ("harness_dsh", "shipped_harness_dsh_host_command"),
+    "HarnessProviderSelection": ("legacy", "HarnessProviderSelection"),
+    "LegacyBundleAdapter": ("legacy", "LegacyBundleAdapter"),
+    "LegacyBundleCompatibilityError": ("legacy", "LegacyBundleCompatibilityError"),
+    "LegacyHarnessSource": ("legacy", "LegacyHarnessSource"),
+}
+
+__all__ = list(_EXPORTS)
+
+
+def __getattr__(name: str) -> Any:
+    try:
+        relative_module, attribute = _EXPORTS[name]
+    except KeyError:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}") from None
+    module = import_module(f"{__name__}.{relative_module}")
+    value = getattr(module, attribute)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted({*globals(), *__all__})

ksadk/plugins/providers/bundles/dsh-knowledge/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-knowledge
+      name: '@kingsoftcloud/dsh-knowledge'

ksadk/plugins/providers/bundles/dsh-knowledge/index.mjs

@@ -0,0 +1,53 @@
+export const name = 'dsh-knowledge'
+export const inject = ['tools', 'platformResources']
+
+export function apply(ctx) {
+  ctx.effect(() => ctx.platformResources.registerTool('search_knowledge_base', 'search_knowledge_base'))
+  ctx.tools.register({
+    name: 'search_knowledge_base',
+    description: 'Search the knowledge base bound to this Agent and return document sources.',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Non-empty query, at most 16000 characters.' },
+        top_k: { type: 'integer', description: 'Positive result count, capped by the binding policy.' },
+      },
+      required: ['query'],
+      additionalProperties: false,
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          status: { type: 'string', enum: ['ok', 'empty', 'failed'] },
+          bindingId: { type: 'string' },
+          items: { type: 'array', items: {
+            type: 'object',
+            properties: {
+              documentId: { type: 'string' }, documentName: { type: 'string' },
+              segmentId: { type: 'string' }, content: { type: 'string' }, score: { type: 'number' },
+            },
+            required: ['documentId', 'documentName', 'segmentId', 'content', 'score'],
+            additionalProperties: false,
+          } },
+          truncated: { type: 'boolean' }, requestId: { type: 'string' },
+          errorCode: { oneOf: [
+            { type: 'string', enum: ['KNOWLEDGE_RETRIEVAL_FAILED', 'RESOURCE_FORBIDDEN'] }, { type: 'null' },
+          ] },
+        },
+        required: ['status', 'bindingId', 'items', 'truncated', 'requestId'],
+        additionalProperties: false,
+      },
+      render(_args, result) {
+        const text = result.status === 'failed' ? 'Knowledge retrieval failed.'
+          : result.status === 'empty' ? 'No matching knowledge found.'
+          : result.items.map(item => `[${item.documentName || item.documentId}] ${item.content}`).join('\n\n')
+        return [{ type: 'text', text }]
+      },
+    },
+    isConcurrencySafe: () => true,
+    execute(args, execution) {
+      return ctx.platformResources.call('search_knowledge_base', args, { signal: execution.signal })
+    },
+  })
+}

ksadk/plugins/providers/bundles/dsh-knowledge/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@kingsoftcloud/dsh-knowledge",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Private development bundle for Agent-bound knowledge retrieval",
+  "exports": {".": "./index.mjs", "./cordis.patch.yml": "./cordis.patch.yml"},
+  "files": ["index.mjs", "cordis.patch.yml"],
+  "engines": {"node": ">=22.19.0"},
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
+    "@kingsoftcloud/dsh-platform-resources": "0.1.0"
+  },
+  "dsh": {"bundle": {"patch": "./cordis.patch.yml"}}
+}

ksadk/plugins/providers/bundles/dsh-memory/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-memory
+      name: '@kingsoftcloud/dsh-memory'

ksadk/plugins/providers/bundles/dsh-memory/index.mjs

@@ -0,0 +1,175 @@
+export const name = 'dsh-memory'
+export const inject = ['tools', 'platformResources']
+
+export function apply(ctx) {
+  for (const operation of ['update_memory', 'delete_memory']) {
+    const updating = operation === 'update_memory'
+    ctx.effect(() => ctx.platformResources.registerTool(operation, operation))
+    ctx.tools.register({
+      name: operation,
+      description: updating
+        ? 'Update a real memory ID recalled in this activation, after host approval. No versioned CAS is supported. Use only the returned new ID; if absent, search again.'
+        : 'Soft-delete a real memory ID recalled in this activation, after host approval. This does not guarantee physical erasure.',
+      parameters: {
+        type: 'object', properties: {
+          memoryId: { type: 'string', minLength: 1, maxLength: 256 },
+          ...(updating ? { content: { type: 'string', minLength: 1, maxLength: 8192 } } : {}),
+        },
+        required: updating ? ['memoryId', 'content'] : ['memoryId'], additionalProperties: false,
+      },
+      output: {
+        schema: {
+          type: 'object', properties: {
+            status: { type: 'string', enum: ['succeeded', 'failed', 'unknown'] },
+            operationId: { type: 'string' }, memoryId: { type: 'string' },
+            newMemoryId: { oneOf: [{ type: 'string' }, { type: 'null' }] },
+            errorCode: { oneOf: [{ type: 'string' }, { type: 'null' }] },
+          },
+          required: ['status', 'operationId', 'memoryId', 'newMemoryId', 'errorCode'],
+          additionalProperties: false,
+        },
+        render(_args, result) {
+          const text = result.status === 'unknown'
+            ? 'Memory mutation outcome is unknown. Do not submit it again automatically.'
+            : result.status === 'failed' ? 'Memory mutation was not completed. Search again before proposing another change.'
+            : !updating ? 'Memory soft-deletion confirmed. This receipt does not prove physical erasure.'
+            : result.newMemoryId ? `Memory update confirmed. Returned record ID: ${result.newMemoryId}.`
+            : 'Memory update confirmed, but its resulting record ID is unavailable. Search again before another change.'
+          return [{ type: 'text', text }]
+        },
+      },
+      isConcurrencySafe: () => false,
+      async execute(args, execution) {
+        const result = await ctx.platformResources.call(operation, args, { signal: execution.signal })
+        if (!['succeeded', 'failed', 'unknown'].includes(result.status)
+          || !/^[0-9a-f]{64}$/.test(result.operationId)
+          || (result.memoryId !== undefined && result.memoryId !== args.memoryId)
+          || (result.newMemoryId !== undefined && typeof result.newMemoryId !== 'string')
+          || (result.status !== 'succeeded' && result.newMemoryId)
+          || (!updating && result.newMemoryId)
+          || (result.errorCode != null && ![
+            'MEMORY_MUTATION_UNKNOWN', 'MEMORY_RECORD_NOT_OBSERVED', 'MEMORY_RECORD_NOT_FOUND',
+          ].includes(result.errorCode))) throw new Error('MEMORY_RESPONSE_INVALID')
+        return {
+          status: result.status, operationId: result.operationId,
+          memoryId: args.memoryId, newMemoryId: result.newMemoryId || null,
+          errorCode: result.errorCode ?? (result.status === 'unknown' ? 'MEMORY_MUTATION_UNKNOWN' : null),
+        }
+      },
+    })
+  }
+  ctx.effect(() => ctx.platformResources.registerTool('memory_status', 'memory_status'))
+  ctx.tools.register({
+    name: 'memory_status',
+    description: 'Check an owned memory submission receipt without resubmitting it. Extraction completion does not prove search indexing is ready.',
+    parameters: {
+      type: 'object', properties: { operationId: { type: 'string', pattern: '^[0-9a-f]{64}$' } },
+      required: ['operationId'], additionalProperties: false,
+    },
+    output: {
+      schema: {
+        type: 'object', properties: {
+          operationId: { type: 'string' }, status: { type: 'string' },
+          extractionStatus: { type: 'string' }, searchable: { type: 'boolean' },
+          errorCode: { oneOf: [{ type: 'string' }, { type: 'null' }] },
+        },
+        required: ['operationId', 'status', 'extractionStatus', 'searchable', 'errorCode'],
+        additionalProperties: false,
+      },
+      render(_args, result) {
+        return [{ type: 'text', text: `Memory extraction: ${result.extractionStatus}. Search indexing has not been confirmed.` }]
+      },
+    },
+    isConcurrencySafe: () => true,
+    execute(args, execution) {
+      return ctx.platformResources.call('memory_status', args, { signal: execution.signal })
+    },
+  })
+  ctx.effect(() => ctx.platformResources.registerTool('save_memory', 'save_memory'))
+  ctx.tools.register({
+    name: 'save_memory',
+    description: 'Submit an explicitly authorized memory for this user. Acceptance is pending extraction, not confirmation that it can be recalled.',
+    parameters: {
+      type: 'object', properties: { content: { type: 'string', minLength: 1, maxLength: 8192 } },
+      required: ['content'], additionalProperties: false,
+    },
+    output: {
+      schema: {
+        type: 'object', properties: {
+          status: { type: 'string', enum: ['accepted_pending', 'unknown', 'searchable', 'failed'] },
+          operationId: { type: 'string' }, searchable: { type: 'boolean' },
+        },
+        required: ['status', 'operationId', 'searchable'], additionalProperties: false,
+      },
+      render(_args, result) {
+        const text = result.status === 'accepted_pending' ? 'Memory accepted; extraction is pending.'
+          : result.status === 'searchable' ? 'Memory indexing confirmed.'
+          : result.status === 'failed' ? 'Memory submission failed.'
+          : 'Memory submission outcome is unknown. Do not submit it again automatically.'
+        return [{ type: 'text', text }]
+      },
+    },
+    isConcurrencySafe: () => false,
+    async execute(args, execution) {
+      const result = await ctx.platformResources.call('save_memory', args, { signal: execution.signal })
+      if (!['accepted_pending', 'unknown', 'searchable', 'failed'].includes(result.status)
+        || typeof result.operationId !== 'string') throw new Error('MEMORY_RESPONSE_INVALID')
+      return {
+        status: result.status, operationId: result.operationId,
+        searchable: result.status === 'searchable',
+      }
+    },
+  })
+  ctx.effect(() => ctx.platformResources.registerTool('load_memory', 'load_memory'))
+  ctx.tools.register({
+    name: 'load_memory',
+    description: 'Recall memories for the authenticated user from this Agent’s bound memory instance.',
+    parameters: {
+      type: 'object',
+      properties: { query: { type: 'string', maxLength: 16000 } },
+      required: ['query'], additionalProperties: false,
+    },
+    output: {
+      schema: {
+        type: 'object',
+        properties: {
+          status: { type: 'string', enum: ['ok', 'empty', 'failed', 'unauthorized'] },
+          items: { type: 'array', items: {
+            type: 'object',
+            properties: {
+              memoryId: { type: 'string' }, content: { type: 'string' },
+              score: { oneOf: [{ type: 'number' }, { type: 'null' }] },
+              version: { oneOf: [{ type: 'integer' }, { type: 'null' }] },
+            },
+            required: ['memoryId', 'content', 'score', 'version'], additionalProperties: false,
+          } },
+          truncated: { type: 'boolean' },
+          errorCode: { oneOf: [{ type: 'string' }, { type: 'null' }] },
+        },
+        required: ['status', 'items', 'truncated', 'errorCode'], additionalProperties: false,
+      },
+      render(_args, result) {
+        const text = result.status === 'empty' ? 'No matching memories found.'
+          : result.status !== 'ok' ? 'Memory retrieval unavailable.'
+          : result.items.map(item => `[${item.memoryId}] ${item.content}`).join('\n\n')
+        return [{ type: 'text', text }]
+      },
+    },
+    isConcurrencySafe: () => true,
+    async execute(args, execution) {
+      const result = await ctx.platformResources.call('load_memory', args, { signal: execution.signal })
+      if (!['ok', 'failed', 'unauthorized'].includes(result.status) || !Array.isArray(result.records)) {
+        throw new Error('MEMORY_RESPONSE_INVALID')
+      }
+      // Tenant/user partition and internal provenance remain host-side.
+      const items = result.status === 'ok' ? result.records.map(record => ({
+        memoryId: record.memory_id, content: record.content,
+        score: record.metadata?.score ?? null, version: record.version ?? null,
+      })) : []
+      return {
+        status: result.status === 'ok' && items.length === 0 ? 'empty' : result.status,
+        items, truncated: Boolean(result.truncated_by_budget), errorCode: result.error_code ?? null,
+      }
+    },
+  })
+}

ksadk/plugins/providers/bundles/dsh-memory/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@kingsoftcloud/dsh-memory",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Private development bundle for Agent-bound memory tools",
+  "exports": {".": "./index.mjs", "./cordis.patch.yml": "./cordis.patch.yml"},
+  "files": ["index.mjs", "cordis.patch.yml"],
+  "engines": {"node": ">=22.19.0"},
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-tools": "^0.1.1-rc.2",
+    "@kingsoftcloud/dsh-platform-resources": "0.1.0"
+  },
+  "dsh": {"bundle": {"patch": "./cordis.patch.yml"}}
+}