Skip to content

feat(pawapp): redesign the SDK and app control plane - #7874

Open
cyruszhang wants to merge 107 commits into
agentscope-ai:mainfrom
cyruszhang:dev/pawapp-vnext
Open

feat(pawapp): redesign the SDK and app control plane#7874
cyruszhang wants to merge 107 commits into
agentscope-ai:mainfrom
cyruszhang:dev/pawapp-vnext

Conversation

@cyruszhang

@cyruszhang cyruszhang commented Sep 19, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

What Problem This Solves

PawApps can expose durable work to Main Chat and their own UI through a shared, scoped Host contract. Small Apps register an app.action handler; external runtimes implement the adapter protocol. Host owns task identity, retries, permissions, setup, questions, approvals, results, artifacts and continuation delivery.

For example, Creator can pause production for generation authorization or content review. Main Chat shows what is being approved and the task's approval progress. Users can authorize clearly scoped generation in chat; content review opens the exact pending review and revision in Creator. Decisions resume the same project/task through Creator's existing mechanisms. A manual review no longer appears as ongoing planning.

This PR includes:

  • Generated Python/JSON Schema/TypeScript contracts, validated results and scoped clients.
  • Durable task execution/recovery, grants, artifacts, handoffs and App-owned configuration prompts.
  • Main Chat discovery/delegation tools, generic task cards and scoped continuation back into the originating chat.
  • Typed execution/review approvals with immutable proposal digests, stable decision IDs, optional cost information and expiry, authenticated user identity and persisted decision receipts. Ordinary agent answers cannot approve. Retries retain the same command identity; stale or conflicting decisions are rejected.
  • Revoked action grants block new work and approvals while scoped owners retain redacted control status and can request cancellation. Cancellation delivery is durable; unavailable or incompatible executors remain unconfirmed. Recovery backs off without fabricating terminal states and observes already-started work without restarting managed handlers. Managed approval waits report expiry to App handlers, wake on decisions with a durable fallback, and preserve the current proposal across progress updates. Large artifact hashes run off the event loop.
  • Approval cards show bounded object/operation scope, operation count and revision, with authenticated inspection handoffs. App-only review is enforced on the server. Mutable progress counts stay separate from the immutable proposal; future counts distinguish unknown, estimated and exact. Creator reports authoritative handled/pending counts and leaves future approvals unknown.
  • Creator story-writing integration: the bilingual skill hands the full StoryPackage and exact script to prepare-production; revise-story preserves revisions; produce-video continues the same project with setup/approval gates and verified final-film publication. Generation approvals and content review use shared cards; new content reviews require inspection and decisions inside Creator.
  • An App-independent word-counter quickstart, managed-handler approval API and generic conformance tests.

App integrations are separate

Both are draft follow-ups to rebase after this SDK merges. Neither App implementation is included here. The shared conformance suite runs without either integration or an external Data Engine.

Compatibility and behavior

  • Existing authorization/event digests and accepted task identities remain compatible. Legacy persisted question-shaped approval events retain their original replay payload; new events use typed approvals.
  • Versioned PawApps require explicit activation. Managed child services inherit OS basics plus explicitly declared environment variables.
  • Each new Creator action needs its own grant. Setup completion, action permissions and per-operation approval remain separate. Host does not change App YOLO settings or model/credential configuration.
  • Creator validates its authoritative authorization/review token before applying decisions. A lost response reuses the existing decision journal; decisions already made inside Creator invalidate stale chat proposals.
  • Artifacts remain reusable across sessions within authorized user/workspace/App scope; cross-App handoffs require exact-version grants.
  • Story references and notes are retained. Binary reference transfer and multi-film production are outside this increment.

Evidence

Local verification for the review follow-up (2026-10-27): 734 backend tests passed, including the PawApp conformance and Creator workflow suites. Regression cases cover revoked-grant cancellation, status redaction, unknown cancellation for missing/changed executors, recovery backoff and restart, App-side approval observation, approval expiry/restart, progress interleaving and artifact hashing. Changed-file pre-commit checks and contract drift checks passed. The isolated deterministic Creator browser acceptance passed with fake providers (image/video approvals, reload, exact handoff and artifact download); no paid calls.

Local verification for the approval contract and Creator adaptation (2026-10-23):

  • 575 backend tests passed: tests/unit/pawapp, Creator's video-workflow suite and project-file review tests. Covers authenticated decisions, cross-scope rejection, expiry/replacement, concurrent decisions, restart/replay, App-side decisions and lost-receipt recovery; also immutable approval content during progress updates, App-only decision enforcement, and stale inspection rejection.
  • 135 frontend tests passed: 129 Console task-card/API/SDK tests plus 6 Creator decision-tray/plugin-entry tests. Covers scope details, forecast certainty, precise inspection routing and revision mismatch handling.
  • TypeScript, both frontend builds, generated-contract drift checks, git diff --check and changed-file pre-commit hooks passed.
  • Deterministic browser acceptance passed: image approval, video approval, reload recovery, exact Creator authorization inspection, completion and verified artifact download. No paid provider calls. The local 8088 instance was updated and restarted; Main Chat and Creator health checks passed.

Documentation: docs/design/pawapp-app-quickstart.md, docs/design/pawapp-approvals.md, docs/design/pawapp-task-runtime.md, docs/design/pawapp-creator-story-handoff.md, and docs/design/pawapp-contract-progress.md.

cyruszhang and others added 30 commits August 27, 2026 17:19
@cyruszhang
docs(qwenpaw-data): align .env/Configure promises with datasource design
08d8819 
TC-DATA-04: SQL datasource credentials are registered through the
context service's datasource API (embedded console Data Sources page),
not via .env or a Configure section. Update the config.py docstring and
README Configure section to state the actual contract.
@cyruszhang
Merge branch 'main' into dev/qwenpaw-data-app
b5d2df7
@cyruszhang
feat(qwenpaw-data): drive the chat workspace on the engine runtime
aca354a 
Replace the host agent-loop chat with the QwenPaw-Data engine: a managed
engine sidecar (uvicorn host-core service) wired to the context service
and model config, an authenticated /engine proxy with SSE pass-through,
and a ChatWorkspace that creates engine sessions/chats, streams the turn
from the event API, restores history by replaying persisted events, and
resumes still-running turns. Adds mid-run steering from the composer,
clarification (ask_user_question) cards answered back into the runtime,
follow-up suggestion chips, and a stop control.
@cyruszhang
feat(qwenpaw-data): render plan, milestones and artifacts in the chat
e29cdfd 
Bring the transcript up to the console workbench: an analysis-plan
panel from task_status graph snapshots, a BizTrace milestone timeline
with durations and span markup stripped to plain text, and an artifact
strip that downloads real files through the new engine artifacts route.
All three restore on history replay since they reduce from the same
persisted event stream.
@cyruszhang
fix(qwenpaw-data): stream chat events over GET and provision the engi…
84325b9 
…ne .mcp

Two defects found by the first live browser run of the engine-native chat:

- paw.api.events defaults to POST, but the engine's chat events route only
  accepts GET, so every stream subscription died with 405 and the chat
  reported "PawApp API error 405". Pass method: "GET" explicitly.

- The managed engine sidecar started with an empty workspace .mcp, so
  sandboxed agents had no DataBridge tools and correctly refused to run any
  analysis. The CLI provisions this file via "qwenpaw-data mcp import", but
  nothing did so for the managed engine. provision_engine_mcp() now upserts
  the databridge entry (CM URL + bearer token) on every engine start while
  preserving user-added entries and recovering from corrupt files.
@cyruszhang
feat(qwenpaw-data): settlement cards and scheduled analyses in the app
d2d3ff4 
Track-A step 3, built native against the OSS engine API with the Cloud
console UX as reference:

- SettlementPanel surfaces pending knowledge cards under the transcript
  (poll follows the engine's pending->queried contract, refreshes when a
  turn completes); confirm triggers the CM write-back, dismiss archives.
  Card titles and field ordering mirror the Cloud console.
- New Automations page lists console cron jobs with create/pause/resume/
  run-now/delete; jobs deliver to the engine session runtime. IM-channel
  targeting stays out of scope until channel binding lands in the app.
- engineApi grows typed settlement + cron wrappers; 6 new tests.
@cyruszhang
feat(qwenpaw-data): console-grade segment cards, artifact previews, t…
71b447c 
…hinking card

Phase 1 of console-parity for the engine-native chat:

- Segments render as rich cards (title + duration, Input/Execution/
  Conclusion markdown blocks with highlighted conclusion, and key-artifact
  rows with descriptions) instead of a thin collapsible timeline. The
  engine's biztrace frames already carry the full structure.
- Artifacts (message strip and per-segment) become card rows with preview
  and download actions; an in-app modal previews HTML reports in a
  sandboxed iframe, images inline, and csv/md/json as text.
- Fix a latent step-2 bug found live: downloadArtifact embedded the query
  string in the request path, which the host SDK's scoped-path validation
  rejects ("Invalid PawApp scoped path"), so every artifact download
  silently failed in the browser; the path now goes through options.query.
- The streaming analysis trace collapses into a thinking card: closed by
  default with a one-line ticker of the latest narration, markdown-rendered
  when expanded, so raw model narration no longer dominates the transcript.
@cyruszhang
feat(qwenpaw-data): embed the full engine console for console-grade UX
38bc658 
Replace the plugin-native chat, cron, and settlement views with the real
engine console, vendored as a hash-routed static SPA by the new
scripts/sync-console-ui.sh (same pattern as the Context console embed).
The build is patched via a checked-in git patch — hash routing, /api/v1
gateway paths, SSO shimmed out, MCP settings dropped, and Skills Hub
routed to an open-source contribution page — with an internal-marker
scan gating the vendored output.

The Analyze and Automations tabs now drive one iframe (console home and
cron-jobs routes); ChatWorkspace, CronJobs, SettlementPanel, and the
orphaned GraphExplorer/SemanticCatalog components are removed along with
their tests.
@cyruszhang
fix(qwenpaw-data): stage the vendored engine console in dev installs
7cb05f8
@cyruszhang
feat(qwenpaw-data): let the engine console own the app surface
cf58069 
The embedded console ships its own navigation (sessions, Skill Hub,
scheduled results, settings), so wrapping it in the plugin's
Analyze/Manage rail duplicated every affordance. The shell is now a
slim topbar hosting only what the console does not own — runtime
health, the DataBridge management console, and plugin configuration —
each toggling over the full-bleed console.
@cyruszhang
refactor(qwenpaw-data): blank the banner and drop the embedded Contex…
71614cc 
…t console

The console sidebar already carries the brand, so the topbar keeps only
the action cluster (status chip, configuration, language). The Manage
iframe goes away: the console's own DataBridge entry and the health
page's "Manage sources" now open the Context console in a full tab,
which beats a second baked-in iframe. The health page loses the summary
card that duplicated the runtime-status cards below it.
@cyruszhang
fix(qwenpaw-data): hide the account menu when the host owns authentic…
16abe59 
…ation

The QwenPaw host authenticates the app, so the console's User Center /
Change Password / Sign Out menu is dead weight in the embed. The patch
now gates the account dropdown on a resolved host user, which the
disabled-auth bootstrap never provides.
@cyruszhang
feat(qwenpaw-data): retire the shell topbar; console owns the surface
1ec53ce 
Model setup now lives in the console's Agent Configuration page (the
engine serves its runtime-settings routes), and the console's language
toggle covers i18n, so the plugin topbar had nothing left to host. The
settings menu gains an App Configuration entry that asks the parent
frame (postMessage) to open the remaining native page — context service
infrastructure — as a closeable overlay. The diagnostics page and its
status model are removed; the console surfaces engine failures itself.
@cyruszhang
refactor(qwenpaw-data): move DataBridge settings into the console
c76ded9 
The overlay page broke the console's design language and its model card
read as a duplicate of Agent Configuration. The settings menu now opens
a console-native DataBridge Configuration page (ConsoleRouteHeader +
antd cards, same flow as Agent/Channel Configuration) scoped to what
Agent Configuration does not cover: the semantic service's own model,
the embedding model, and the Neo4j graph store — with an explicit
pointer that the analysis agent's model lives in Agent Configuration.
The page talks to the hosting app's backend, which gains a
restart-context endpoint replacing the host-SDK dependency action.

The native shell collapses to a bootstrap that mounts the console
iframe; Configure, the string tables, icons, and the API client are
gone (styles.css 2983 → 125 lines).
@cyruszhang
style: apply pre-commit auto-fixes (black, trailing commas, whitespace)
8e91dbc
@cyruszhang
style: settle add-trailing-comma/black fixpoint on engine_gateway
a1b2404
@cyruszhang
feat(qwenpaw-data): bridge QwenPaw channels to the analysis engine
299611a 
Route IM conversations through QwenPaw's own channel infrastructure
instead of the engine's channel connectors: a session-gated on_reply
middleware (/data on|off) forwards turns to the engine's SSE API and
re-emits frames as AgentScope events, so streaming text/reasoning,
image artifacts, clarification round-trips (numbered-text answer +
resume via after_sequence_number), followups, and /stop work on any
configured channel. Adds /datasource selection, a per-session bridge
store, and denies the engine's channel-management routes through the
gateway; the vendored console drops its Channel Configuration page.

SDK: implement ctx.notify via workspace.channel_manager, add
app.middleware() passthrough, and wire the previously-dead
@app.command buffer to register_slash_command.
@cyruszhang
fix(qwenpaw-data): stage the backend/bridge package in dev.sh
9390756 
The staging step copied only top-level backend/*.py, so hot-installs
were missing the channel-bridge subpackage and the plugin failed to
load.
@cyruszhang
fix(qwenpaw-data): allow long engine stop unwinds in the bridge
8a34679 
The engine's stop route awaits the full ChatRuntime cancellation,
which can exceed the client's default 30s read timeout mid-sandbox
step; the best-effort stop then failed with ReadTimeout and left the
engine chat running.
@cyruszhang
Merge pull request #17 from cyruszhang/feat/engine-native-chat
cba4467 
feat(qwenpaw-data): ship the engine console as the app surface
@cyruszhang
feat(qwenpaw-data): vendor the reviewed Data console snapshot
a718f85
@cyruszhang
chore(qwenpaw-data): prepare PawApp 0.1.2
4556844
@cyruszhang
docs(qwenpaw-data): design ecosystem interoperability
f1251ba
@cyruszhang
fix(qwenpaw-data): require the QPD 0.3 runtime
d039750
@cyruszhang
fix(qwenpaw-data): connect the demo context stack
d2c2827 
Use the QPD 0.3 Neo4j settings and allow the Compose service hostname so seeding and graph access work from containers.
@cyruszhang
fix(qwenpaw-data): satisfy console verification checks
f04c6f5
@cyruszhang
Merge pull request #18 from cyruszhang/feat/engine-native-chat
7cce73e 
feat(qwenpaw-data): adopt the QPD 0.3 runtime
@cyruszhang
Merge upstream main into dev/qwenpaw-data-app
fb2a286
@cyruszhang
fix(qwenpaw-data): harden gateway input validation
0f0e7da 
Replace backtracking-prone route and datasource regex handling with deterministic validation to address CodeQL findings without changing supported flows.
@cyruszhang
fix(qwenpaw-data): forward only validated engine paths
94044c0 
Use the canonical allowlisted path at the outbound request boundary so encoded client input cannot bypass gateway validation.
@github-actions github-actions Bot mentioned this pull request Oct 23, 2026
Open
@github-actions github-actions Bot mentioned this pull request Oct 24, 2026
Open
@github-actions github-actions Bot mentioned this pull request Oct 27, 2026
Open
@github-actions github-actions Bot mentioned this pull request Oct 30, 2026
Open

This branch is waiting to be deployed

2 waiting deployments
maintainer-approved — 491baa4a Waiting Oct 29, 2026 by cyruszhang via Maintainer Approval #11006
ai-review-approved — 491baa4a Waiting Oct 29, 2026 by cyruszhang via AI Review Approval #5440
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

size/XXXL 4000+ changed lines (additions + deletions)

Projects

QwenPaw
Status: Todo

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@cyruszhang