@xiaozhiclaw/qlogicagent-core 0.1.5 → 0.2.0

package/README.md

@@ -1,40 +1,70 @@
 # @xiaozhiclaw/qlogicagent-core
 
-Host-neutral qlogicagent turn and tool-loop runtime for server embedding.
+Shared Agent runtime for SaaS systems. AgentAtlas and AstraCAD host the same
+canonical inference/tool loop in their own existing services.
+
+The package exports three factories:
+
+- `createCloudAgent`: trusted application/tenant/actor/scope identity, fresh
+  authorization, complete structured results, checkpoints and confirmed resume.
+- `createCloudTaskRuntime`: product-owned durable tasks, cursor events, explicit
+  input/confirmation/external waits, cancellation and fenced recovery.
+- `createEmbeddedAgent`: existing low-level SaaS embedding contract.
+
+The product injects model transport, tool execution, logging, authorization and
+persistence. Login, permissions, conversations, business commits, audit, files,
+database connections and workers remain with the product. Model routing,
+credentials and accounting remain with its model service.
 
 ```ts
-import {
-  createEmbeddedAgent,
-  type LLMTransport,
-  type ToolInvoker,
-} from "@xiaozhiclaw/qlogicagent-core";
-
-const agent = createEmbeddedAgent({
-  llmTransport: transport satisfies LLMTransport,
-  toolInvoker: tools satisfies ToolInvoker,
-  apiKey: process.env.MODEL_API_KEY,
-  maxRounds: 6,
+import { createCloudAgent } from "@xiaozhiclaw/qlogicagent-core";
+
+const agent = createCloudAgent({
+  llmTransport: productModelTransport,
+  authorize: (context, action) => product.revalidateAccess(context, action),
+  checkpoints: { save: checkpoint => product.saveCheckpoint(checkpoint) },
+  onToolResult: (invocation, result) => product.saveToolReceipt(invocation, result),
+  toolInvoker: { invoke: (invocation, signal) => product.executeTool(invocation, signal) },
 });
 
 for await (const event of agent.run({
-  turnId: crypto.randomUUID(),
-  sessionId: conversationId,
-  messages,
-  tools,
-  config: { model: "model-id", maxToolCalls: 3 },
-})) {
-  // Persist or forward the typed turn events required by the host product.
+  turnId, sessionId,
+  context: { applicationId, tenantId, actorId, scopeId, definitionVersion },
+  messages, tools,
+  config: { model, maxRounds: 8, maxToolCalls: 5, maxConcurrentTools: 1 },
+}, signal)) {
+  await product.persistAndProjectEvent(event);
 }
 ```
 
-The embedding boundary owns model/tool turn behavior plus host-neutral response
-content blocks, standard presentation-tool contracts, and engineering-file
-evidence extraction. Choice, table, diagram, attachment, and 2D/3D engineering
-semantics therefore stay consistent across desktop, SaaS, and future hosts.
-Each host remains responsible for rendering those semantics with its own UI.
-
-The caller retains
-authentication, tenant and conversation authority, persistence, knowledge,
-business workflows, and deployment. The package does not require the desktop
-Host, ACP, MCP, SQLite, Redis, Skills, sub-agents, filesystem tools, or shell
-tools.
+Context comes from the authenticated product, never from a model/browser claim.
+Skill knowledge is maintained by each product with its module version; MCP may
+be its tool execution protocol. The core does not install capabilities.
+
+Presentation contracts support choices, tables, diagrams, attachments and
+engineering file evidence. Each SaaS renders actual returned content blocks in
+its own UI. Tool names and paths do not imply artifacts or business success.
+
+This library has no production dependencies, CLI, desktop host, local tool
+runtime, native session store or per-process credential/policy discovery.
+Unknown tool effects require product reconciliation before recovery.
+Cloud tasks persist inference attempts before network I/O. Unknown model attempts
+require request-bound model-service evidence; acknowledged original responses can
+be replayed without another inference. Sensitive response bodies are excluded from
+progress events. Provider usage is distinct from settlement evidence.
+
+Optional `assistantContext` binds module schema/prerequisites, enterprise configuration
+and source state, employee permissions, and versioned platform Skill/examples.
+Optional `goal` requires a product `verifyGoal` callback before semantic completion.
+Task request/deadline budgets survive resume; products own atomic financial quota
+reservation through `reserveModelBudget`. Optional delta batching preserves control
+event order and cursor continuity. These contracts do not create new product stores,
+business rules, queues or accounting authorities.
+Model retries require all three transport-error fields `retryable`, `safeToRetry`
+and `automaticRetryAuthorized` to be explicitly true (`ModelRetryAuthorization`).
+An unknown model outcome pauses a durable task for product reconciliation;
+task names and error text cannot authorize another paid inference request.
+
+See the repository's `docs/cloud-runtime.md` for detailed contracts, product
+integration boundaries and acceptance commands. Release status belongs to the
+source workspace README and package registry; this API guide is version-independent.