Skip to content

feat: workflow-definitions, events, and workflow-memory CLI groups#10

Open
arnav2 wants to merge 2 commits into
mainfrom
arnav2/workflow-audit-memory
Open

feat: workflow-definitions, events, and workflow-memory CLI groups#10
arnav2 wants to merge 2 commits into
mainfrom
arnav2/workflow-audit-memory

Conversation

@arnav2
Copy link
Copy Markdown
Contributor

@arnav2 arnav2 commented May 12, 2026

Summary

Adds three new top-level kscli resource groups wrapping the new endpoints shipped in ksapi 1.84.0:

  • kscli workflow-definitions — full lifecycle: create, list, describe, update, delete, invoke, runs. Create takes --name, --runner-type, repeatable --source-path-part-id / --instruction-path-part-id / --output-path-part-id (1–20 each), plus optional --description, --runner-config (JSON), --max-run-duration-seconds, --template-path-part-id.
  • kscli events — audit-log events scoped to a path part: events list <path_part_id> with --kind / --since / --until / --recursive / --limit / --offset, and events append <path_part_id> --kind … [--payload '{…}'].
  • kscli workflow-memory — long-term memory chunks scoped to a workflow definition: list, describe, append (--body, optional --kind ∈ CORRECTION/PREFERENCE/EXAMPLE), edit, forget.

Bumps ksapi>=1.84.0 and repairs collateral SDK renames in existing commands so the bump doesn't regress anything:

  • chunks: ChunkMetadataInputChunkMetadata.
  • tags attach: SDK removed bulk_add_path_part_tags; reimplemented as get_path_part_tags → merge → set_path_part_tags. ⚠️ Contract change: now non-atomic (lost-update race possible) and BulkTagRequest.tag_ids is capped at 10, so attach fails on a path part already at 10 tags. Worth a follow-up if we want to expose set semantics directly.

agent_help and kscli --help auto-pick up the new groups; CLAUDE.md resource list updated. Read-only e2e tests added for each new group, matching the existing convention.

Test plan

  • make pre-commit — green (ruff clean, basedpyright 0 errors, 11/11 unit tests).
  • Verified all e2e failures observed locally reproduce on main baseline — they're caused by the local e2e backend at localhost:28000 being behind on schema migrations (document_checkout table missing, workflow_definition.instruction_path_part_id column-name mismatch) and an unrelated pre-existing Path import bug in tests/e2e/test_cli_folders.py. Not introduced by this PR.
  • Run e2e suite against a backend with the new schema to confirm the read-only tests for workflow-definitions list, events list, and workflow-memory list pass against real data.
  • Manual smoke test of workflow-definitions create + invoke end-to-end.
  • Decide whether to fix the tags attach atomicity regression in a follow-up or expose tags set directly.

🤖 Generated with Claude Code

Wraps three new ksapi surfaces shipped in 1.84.0:

- `kscli workflow-definitions {create,list,describe,update,delete,invoke,runs}`
  — full lifecycle for workflow definitions (WorkflowDefinitionsApi).
- `kscli events {list,append}` — audit-log events on a path part
  (PathPartsApi.{list,append}_path_part_event); supports
  --kind/--since/--until/--recursive filters.
- `kscli workflow-memory {list,describe,append,edit,forget}` — long-term
  memory chunks attached to a workflow definition (WorkflowMemoryApi).

Bumps `ksapi>=1.84.0` and repairs collateral SDK renames so existing
commands keep working:

- `chunks`: `ChunkMetadataInput` → `ChunkMetadata`.
- `tags attach`: SDK removed `bulk_add_path_part_tags`; reimplemented as
  `get_path_part_tags` → merge → `set_path_part_tags`. NOTE: this path is
  now non-atomic (lost-update race possible between read and write) and
  `BulkTagRequest.tag_ids` is capped at 10, so attach will fail on a path
  part that already has 10 tags.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
@arnav2
Copy link
Copy Markdown
Contributor Author

arnav2 commented May 12, 2026

E2E CI failure analysis — not caused by this PR

CI run: 100 passed, 10 failed. All 10 failures share the same backend stderr:

Error: Conflict: 409: A document checkout is required to edit this document.
Acquire one via POST /v1/documents/{id}/checkout first.

Why this isn't this PR's fault

  • The 10 failing tests are all pre-existing Write tests in test_cli_chunks.py, test_cli_documents.py, test_cli_document_versions.py, test_cli_sections.py, test_cli_chunk_lineages.py. None of the three new groups (workflow-definitions, events, workflow-memory) fail — the three new read-only e2e tests are in the 100 passing.
  • The e2e job clones ks-backend@HEAD with no version pin, so CI tests against the latest backend, which now enforces a checkout protocol on write paths.
  • The SDK exposes no checkout endpoint. Confirmed by grepping ksapi 1.84.0:
    • 0 methods matching checkout on any *Api class.
    • 0 models matching checkout.
    • The only related pattern in the SDK is WorkflowRunsApi.{acquire,release}_workflow_run_lock for workflow runs, not documents.
  • Main today would show the same failures: backend enforcement is server-side and SDK-version-independent. The last main CI run (May 4) had only 1 failure (tags attach, an SDK-rename issue) — the checkout-required regression came in afterwards on the backend side.

Unblock path (out of scope for this PR)

  1. ks-backend: expose POST /v1/documents/{id}/checkout (and the release counterpart) in the OpenAPI spec.
  2. Regen ksapi: bump to a version that includes the new endpoints, and ksapi pin updated here.
  3. Follow-up ks-cli PR: wrap each affected Write command (documents delete, document-versions create/clear, sections {create,update,delete}, chunks {create,update,delete}, chunk-lineages {create,delete}) in acquire-checkout → mutate → release-checkout. Non-trivial refactor; deserves its own PR + tests.

Recommend landing this PR on the strength of the three new groups + the SDK-bump repair, with the checkout work tracked separately.

The backend now requires a write lock (POST /v1/documents/{id}/checkout)
before mutating a document, its versions, sections, chunks, or lineage.
ksapi does not yet expose the checkout endpoints, so this commit adds a
small helper that calls them via the SDK's raw `param_serialize` +
`call_api` path while reusing the authenticated `ApiClient`.

The helper exposes:
- `with_document_checkout(api_client, path_part_id)` — context manager
  that acquires on enter and releases on exit (release errors are
  swallowed and logged; the server-side TTL will reap the lock anyway).
- `resolve_document_path_part_id` / `resolve_version_document_path_part_id`
  / `resolve_ancestor_document_path_part_id` — helpers to find the
  governing document's path_part_id starting from a document id, a
  version id, or any descendant path_part_id (walks parent chain until
  a DOCUMENT node).

Each affected write command resolves the document and wraps its
mutation in the context manager:

- documents: `update`, `delete`
- document-versions: `create`, `update`, `delete`, `clear-contents`
- sections: `create`, `update`, `delete`
- chunks: `create`, `update`, `update-content`, `delete`
- chunk-lineages: `create`, `delete`

All 12 previously-failing Write e2e tests now pass locally.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant