okstra 0.235.0 → 0.237.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/lib/host-registry-client.d.mts +9 -2
- package/dist/lib/host-registry-client.mjs +29 -3
- package/dist/lib/host-registry-client.mjs.map +1 -1
- package/dist/lib/runtime-payload.mjs +1 -0
- package/dist/lib/runtime-payload.mjs.map +1 -1
- package/docs/architecture/storage-model.md +1 -0
- package/docs/architecture.md +2 -2
- package/docs/cli.md +6 -0
- package/package.json +1 -1
- package/runtime/BUILD.json +2 -2
- package/runtime/bin/lib/okstra/usage.sh +8 -8
- package/runtime/bin/okstra-qwen-exec.sh +5 -0
- package/runtime/prompts/lead/convergence.md +4 -1
- package/runtime/prompts/lead/okstra-lead-contract.md +4 -4
- package/runtime/prompts/profiles/_clarification-recommendation.md +1 -1
- package/runtime/prompts/profiles/_common-contract.md +10 -1
- package/runtime/prompts/wizard/prompts.ko.json +16 -4
- package/runtime/python/okstra_ctl/adapters/providers/antigravity/adapter.py +10 -2
- package/runtime/python/okstra_ctl/adapters/providers/claude/adapter.py +16 -1
- package/runtime/python/okstra_ctl/adapters/providers/codex/adapter.py +20 -5
- package/runtime/python/okstra_ctl/adapters/providers/kimi/adapter.py +17 -9
- package/runtime/python/okstra_ctl/adapters/providers/qwen/adapter.py +88 -0
- package/runtime/python/okstra_ctl/adapters/providers/qwen/manifest.json +1 -0
- package/runtime/python/okstra_ctl/adapters/providers/qwen/settings.json +12 -0
- package/runtime/python/okstra_ctl/adapters/providers/zai/adapter.py +8 -2
- package/runtime/python/okstra_ctl/approval_decisions.py +22 -2
- package/runtime/python/okstra_ctl/business_flow/contracts.py +11 -0
- package/runtime/python/okstra_ctl/business_flow/engine.py +90 -32
- package/runtime/python/okstra_ctl/business_flow/hooks.py +4 -2
- package/runtime/python/okstra_ctl/business_flow/source.py +39 -7
- package/runtime/python/okstra_ctl/business_flow/store.py +94 -28
- package/runtime/python/okstra_ctl/convergence.py +95 -5
- package/runtime/python/okstra_ctl/convergence_critic_verify_prompt.py +11 -10
- package/runtime/python/okstra_ctl/convergence_engine.py +30 -15
- package/runtime/python/okstra_ctl/convergence_reverify_prompt.py +9 -2
- package/runtime/python/okstra_ctl/coverage_census.py +75 -12
- package/runtime/python/okstra_ctl/entrypoints/hosts.py +1 -1
- package/runtime/python/okstra_ctl/lead_progress.py +1 -1
- package/runtime/python/okstra_ctl/manager_cli.py +42 -5
- package/runtime/python/okstra_ctl/manager_launch.py +60 -1
- package/runtime/python/okstra_ctl/manager_store.py +45 -0
- package/runtime/python/okstra_ctl/model_discovery.py +1 -1
- package/runtime/python/okstra_ctl/models.py +2 -2
- package/runtime/python/okstra_ctl/phases/discussion/profile.md +2 -2
- package/runtime/python/okstra_ctl/phases/error_analysis/profile.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_option_selection/profile.md +1 -1
- package/runtime/python/okstra_ctl/phases/implementation_planning/authoring.py +2 -1
- package/runtime/python/okstra_ctl/phases/implementation_planning/instructions/plan-body-verification.md +2 -2
- package/runtime/python/okstra_ctl/phases/implementation_planning/profile.md +3 -3
- package/runtime/python/okstra_ctl/phases/requirements_discovery/profile.md +5 -5
- package/runtime/python/okstra_ctl/plan_item_evidence.py +25 -1
- package/runtime/python/okstra_ctl/registry/provider_registry.py +1 -1
- package/runtime/python/okstra_ctl/render_final_report.py +1 -1
- package/runtime/python/okstra_ctl/run.py +1 -1
- package/runtime/python/okstra_ctl/run_context.py +18 -3
- package/runtime/python/okstra_ctl/schema_excerpt.py +14 -9
- package/runtime/python/okstra_ctl/verdict_blocks.py +7 -2
- package/runtime/python/okstra_ctl/wizard/cli.py +14 -2
- package/runtime/python/okstra_ctl/wizard/engine.py +28 -1
- package/runtime/python/okstra_ctl/wizard/ids.py +8 -0
- package/runtime/python/okstra_ctl/wizard/picker_navigation.py +64 -2
- package/runtime/python/okstra_ctl/wizard/roles.py +194 -45
- package/runtime/python/okstra_ctl/wizard/sources.py +10 -1
- package/runtime/python/okstra_ctl/wizard/state.py +71 -21
- package/runtime/python/okstra_ctl/wizard/statefile.py +8 -3
- package/runtime/python/okstra_ctl/wizard/steps_roles.py +6 -3
- package/runtime/python/okstra_ctl/wizard/worker_settings.py +129 -25
- package/runtime/python/okstra_ctl/worker_audit_ledger.py +50 -8
- package/runtime/python/okstra_ctl/worker_prompt_body.py +26 -2
- package/runtime/python/okstra_ctl/worker_prompt_headers.py +12 -9
- package/runtime/python/okstra_token_usage/claude.py +5 -1
- package/runtime/python/okstra_token_usage/collect.py +3 -3
- package/runtime/python/okstra_token_usage/pricing.py +1 -0
- package/runtime/skills/_fragments/wizard-relay-protocol.md +1 -1
- package/runtime/skills/okstra-discussion/SKILL.md +1 -1
- package/runtime/skills/okstra-manager/SKILL.md +8 -2
- package/runtime/skills/okstra-run/SKILL.md +2 -2
- package/runtime/skills/okstra-setup/SKILL.md +34 -5
- package/runtime/skills/okstra-setup/references/project-config.md +19 -0
- package/runtime/templates/worker-prompt-preamble.md +12 -2
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
"""Qwen Code workers using a regional Model Studio API endpoint."""
|
|
2
|
+
import os
|
|
3
|
+
import re
|
|
4
|
+
from collections.abc import Mapping
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
from typing import Any
|
|
7
|
+
from urllib.parse import urlsplit
|
|
8
|
+
|
|
9
|
+
from okstra_ctl.domain.provider import ModelSpec, ProviderSpec
|
|
10
|
+
from okstra_ctl.domain.role import ROLE_DEFINITIONS
|
|
11
|
+
from okstra_ctl.domain.worker_exec import ExecCommand, PolicySupport, WorkerExecRequest
|
|
12
|
+
from okstra_ctl.domain.worker_presentation import JsonEvents
|
|
13
|
+
from okstra_ctl.domain.worker_stream import content_block_events
|
|
14
|
+
|
|
15
|
+
|
|
16
|
+
def observe_usage(event: Mapping[str, Any]) -> Mapping[str, Any] | None:
|
|
17
|
+
usage = event.get("usage") if event.get("type") == "result" else None
|
|
18
|
+
return usage if isinstance(usage, Mapping) and usage else None
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class QwenExecution:
|
|
22
|
+
def build_command(self, request: WorkerExecRequest) -> ExecCommand:
|
|
23
|
+
api_key = os.environ.get("DASHSCOPE_API_KEY", "").strip()
|
|
24
|
+
endpoint = os.environ.get("OKSTRA_QWEN_BASE_URL", "").strip()
|
|
25
|
+
if not api_key:
|
|
26
|
+
raise OSError("DASHSCOPE_API_KEY is required for Qwen workers")
|
|
27
|
+
if not endpoint:
|
|
28
|
+
raise OSError("OKSTRA_QWEN_BASE_URL is required for Qwen workers")
|
|
29
|
+
try:
|
|
30
|
+
parsed = urlsplit(endpoint)
|
|
31
|
+
port = parsed.port
|
|
32
|
+
except ValueError:
|
|
33
|
+
raise OSError("OKSTRA_QWEN_BASE_URL is not a valid Model Studio URL") from None
|
|
34
|
+
host = parsed.hostname or ""
|
|
35
|
+
if parsed.username is not None or parsed.password is not None:
|
|
36
|
+
raise OSError("OKSTRA_QWEN_BASE_URL must not embed credentials")
|
|
37
|
+
regional = re.fullmatch(r"[a-z0-9-]+\.[a-z0-9-]+\.maas\.aliyuncs\.com", host)
|
|
38
|
+
legacy = host in {"dashscope.aliyuncs.com", "dashscope-intl.aliyuncs.com", "cn-hongkong.dashscope.aliyuncs.com"}
|
|
39
|
+
if (parsed.scheme != "https" or not (regional or legacy)
|
|
40
|
+
or port not in (None, 443) or parsed.query or parsed.fragment
|
|
41
|
+
or parsed.path.rstrip("/") != "/compatible-mode/v1"):
|
|
42
|
+
raise OSError("OKSTRA_QWEN_BASE_URL must be an HTTPS Model Studio /compatible-mode/v1 URL without credentials, query or fragment")
|
|
43
|
+
argv = [
|
|
44
|
+
"qwen", "--auth-type", "openai", "--openai-base-url", endpoint,
|
|
45
|
+
"--model", request.model, "--output-format", "stream-json",
|
|
46
|
+
]
|
|
47
|
+
if request.policy.auto_approve:
|
|
48
|
+
argv += ["--approval-mode", "yolo"]
|
|
49
|
+
if request.session_id:
|
|
50
|
+
argv += ["--session-id", request.session_id]
|
|
51
|
+
for directory in request.policy.write_scope:
|
|
52
|
+
argv += ["--include-directories", str(directory)]
|
|
53
|
+
return ExecCommand(
|
|
54
|
+
argv=tuple(argv), stdin_text=request.prompt_text,
|
|
55
|
+
cwd=request.worktree_path or request.project_root,
|
|
56
|
+
environment={
|
|
57
|
+
"OPENAI_API_KEY": api_key, "OPENAI_MODEL": request.model,
|
|
58
|
+
"OKSTRA_QWEN_API_KEY": api_key, "OKSTRA_QWEN_ENDPOINT": endpoint,
|
|
59
|
+
"QWEN_CODE_SYSTEM_SETTINGS_PATH": str(Path(__file__).with_name("settings.json")),
|
|
60
|
+
},
|
|
61
|
+
presentation=JsonEvents(
|
|
62
|
+
normalise=content_block_events,
|
|
63
|
+
# Qwen Code copies config.getModel() into message.model.
|
|
64
|
+
observe=lambda _event: None,
|
|
65
|
+
observe_usage=observe_usage,
|
|
66
|
+
),
|
|
67
|
+
)
|
|
68
|
+
|
|
69
|
+
def policy_support(self) -> PolicySupport:
|
|
70
|
+
return PolicySupport(
|
|
71
|
+
can_auto_approve=True, can_bound_write_scope=False,
|
|
72
|
+
note="Qwen Code approval mode does not enforce filesystem write boundaries",
|
|
73
|
+
)
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def create_provider() -> ProviderSpec:
|
|
77
|
+
roles = frozenset(role.id for role in ROLE_DEFINITIONS if role.id != "leader")
|
|
78
|
+
return ProviderSpec(
|
|
79
|
+
provider="qwen", display_label="Qwen Code",
|
|
80
|
+
models={"qwen4-max": ModelSpec("qwen4-max", "Qwen4 Max", "qwen4-max")},
|
|
81
|
+
default_models={role: "qwen4-max" for role in roles},
|
|
82
|
+
wrapper="okstra-qwen-exec.sh", supported_roles=roles,
|
|
83
|
+
execution_capabilities=frozenset({
|
|
84
|
+
"worker-artifact-io", "source-readonly",
|
|
85
|
+
"extended-artifact-authoring", "project-mutation",
|
|
86
|
+
}),
|
|
87
|
+
exec_strategy=QwenExecution(),
|
|
88
|
+
)
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"schemaVersion": 1, "id": "qwen", "factory": "adapter.py:create_provider"}
|
|
@@ -25,6 +25,8 @@ ZAI_MODELS = {
|
|
|
25
25
|
for name, label, pricing in (
|
|
26
26
|
("glm-5.3", "GLM-5.3", (1.40, 0.26, 4.40)),
|
|
27
27
|
("glm-5.3-flash", "GLM-5.3 Flash", (0.15, 0.03, 0.50)),
|
|
28
|
+
("glm-5.3-flashx", "GLM-5.3 FlashX", (0.37, 0.075, 1.25)),
|
|
29
|
+
("glm-5.3-flashx-legal", "GLM-5.3 FlashX Legal", (0.37, 0.075, 1.25)),
|
|
28
30
|
)
|
|
29
31
|
}
|
|
30
32
|
|
|
@@ -88,10 +90,14 @@ class ZaiExecution:
|
|
|
88
90
|
command = ClaudeExecution().build_command(
|
|
89
91
|
replace(request, reasoning_effort="")
|
|
90
92
|
)
|
|
93
|
+
argv = list(command.argv)
|
|
94
|
+
index = argv.index("--setting-sources")
|
|
95
|
+
# No setting source at all, so a settings file's env cannot override the
|
|
96
|
+
# child environment below.
|
|
97
|
+
argv[index + 1] = ""
|
|
91
98
|
return replace(
|
|
92
99
|
command,
|
|
93
|
-
|
|
94
|
-
argv=(*command.argv, "--setting-sources", ""),
|
|
100
|
+
argv=tuple(argv),
|
|
95
101
|
environment={
|
|
96
102
|
"ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
|
|
97
103
|
"ANTHROPIC_AUTH_TOKEN": api_key,
|
|
@@ -11,6 +11,7 @@ from dataclasses import dataclass
|
|
|
11
11
|
from pathlib import Path
|
|
12
12
|
from typing import Any, Mapping, Sequence
|
|
13
13
|
|
|
14
|
+
from .clarification_items.dispositions import USER_INPUT_BLOCKS
|
|
14
15
|
from .clarification_items.sidecars import (
|
|
15
16
|
sidecar_answers,
|
|
16
17
|
attached_response_sections,
|
|
@@ -57,6 +58,10 @@ SCOPE_EFFECTS = frozenset({"new-schema", "deferrable"})
|
|
|
57
58
|
CLASSIFICATIONS = frozenset(
|
|
58
59
|
{"user-decision", "noncritical-dissent", "correctness-critical"}
|
|
59
60
|
)
|
|
61
|
+
# A phase without an approval gate records its decisions as next-phase blockers
|
|
62
|
+
# (`_common-contract.md` reporter-confirmation precondition); both are the values
|
|
63
|
+
# the gates read as waiting on user input.
|
|
64
|
+
DECISION_BLOCKS = tuple(sorted(USER_INPUT_BLOCKS))
|
|
60
65
|
_FORBIDDEN_BY_CLASSIFICATION = {
|
|
61
66
|
"correctness-critical": frozenset({"select"}),
|
|
62
67
|
"noncritical-dissent": frozenset({"select"}),
|
|
@@ -214,7 +219,12 @@ def _decision_row(
|
|
|
214
219
|
expected_form: str, classification: str, origin: str,
|
|
215
220
|
user_confirmation: str, unblock_condition: str,
|
|
216
221
|
recommended_disposition: str, options: Sequence[DecisionOption],
|
|
222
|
+
blocks: str = "approval",
|
|
217
223
|
) -> dict[str, Any]:
|
|
224
|
+
if blocks not in DECISION_BLOCKS:
|
|
225
|
+
raise ApprovalDecisionError(
|
|
226
|
+
f"invalid blocks: {blocks!r}. Allowed values: " + ", ".join(DECISION_BLOCKS)
|
|
227
|
+
)
|
|
218
228
|
if classification not in CLASSIFICATIONS:
|
|
219
229
|
raise ApprovalDecisionError(f"invalid classification: {classification}")
|
|
220
230
|
_reject_off_enum(origin, "origin", "ClarificationOrigin")
|
|
@@ -232,7 +242,7 @@ def _decision_row(
|
|
|
232
242
|
"kind": "decision",
|
|
233
243
|
"statement": _required(statement, "statement"),
|
|
234
244
|
"expectedForm": _required(expected_form, "expected_form"),
|
|
235
|
-
"blocks":
|
|
245
|
+
"blocks": blocks,
|
|
236
246
|
"origin": _required(origin, "origin"),
|
|
237
247
|
"userConfirmation": _required(user_confirmation, "user_confirmation"),
|
|
238
248
|
"approval": {
|
|
@@ -250,7 +260,7 @@ def open_decision(
|
|
|
250
260
|
classification: str, origin: str, user_confirmation: str,
|
|
251
261
|
unblock_condition: str, recommended_disposition: str,
|
|
252
262
|
options: Sequence[DecisionOption], supersedes: Sequence[str] = (),
|
|
253
|
-
candidate_ref: str = "",
|
|
263
|
+
candidate_ref: str = "", blocks: str = "approval",
|
|
254
264
|
) -> None:
|
|
255
265
|
row = _decision_row(
|
|
256
266
|
clarification_id=clarification_id, ticket_id=ticket_id,
|
|
@@ -258,6 +268,7 @@ def open_decision(
|
|
|
258
268
|
classification=classification, origin=origin,
|
|
259
269
|
user_confirmation=user_confirmation, unblock_condition=unblock_condition,
|
|
260
270
|
recommended_disposition=recommended_disposition, options=options,
|
|
271
|
+
blocks=blocks,
|
|
261
272
|
)
|
|
262
273
|
ledger = _ledger(ledger_path, task_key, task_type, run_seq)
|
|
263
274
|
active = ledger.get("activeClarifications")
|
|
@@ -487,6 +498,15 @@ def _add_open_arguments(parser: argparse.ArgumentParser) -> None:
|
|
|
487
498
|
"candidate's splitAcceptance may cite only a decision opened for it."
|
|
488
499
|
),
|
|
489
500
|
)
|
|
501
|
+
parser.add_argument(
|
|
502
|
+
"--blocks",
|
|
503
|
+
choices=DECISION_BLOCKS,
|
|
504
|
+
default="approval",
|
|
505
|
+
help=(
|
|
506
|
+
"what the open row withholds: approval (the default) or next-phase, "
|
|
507
|
+
"for a phase without an approval gate"
|
|
508
|
+
),
|
|
509
|
+
)
|
|
490
510
|
|
|
491
511
|
|
|
492
512
|
_CLI_EPILOG = r"""Usage:
|
|
@@ -10,6 +10,7 @@ from typing import Any, Literal, TypedDict
|
|
|
10
10
|
from ..report_language import resolve_report_language
|
|
11
11
|
from ..json_boundary import load_owned_object, write_owned_object_atomic
|
|
12
12
|
from ..paths import find_asset_root
|
|
13
|
+
from ..schema_excerpt import reachable_defs
|
|
13
14
|
from ..report_language import is_language_tag
|
|
14
15
|
|
|
15
16
|
OPERATION = "explain-flow"
|
|
@@ -267,6 +268,16 @@ def schema_definition(name: str) -> dict[str, Any]:
|
|
|
267
268
|
return {"$ref": f"#/$defs/{name}", "$defs": schema["$defs"]}
|
|
268
269
|
|
|
269
270
|
|
|
271
|
+
def prompt_schema(name: str) -> dict[str, Any]:
|
|
272
|
+
"""`schema_definition` with only the definitions `name` reaches through
|
|
273
|
+
`$ref`; the stored records (claims, executions, task links) are not part of
|
|
274
|
+
what a model returns."""
|
|
275
|
+
schema = schema_definition(name)
|
|
276
|
+
defs = schema["$defs"]
|
|
277
|
+
kept = reachable_defs(defs, {"$ref": schema["$ref"]})
|
|
278
|
+
return {**schema, "$defs": {key: defs[key] for key in defs if key in kept}}
|
|
279
|
+
|
|
280
|
+
|
|
270
281
|
def read_artifact(path: Path, name: str) -> dict[str, Any]:
|
|
271
282
|
return load_owned_object(
|
|
272
283
|
path, artifact=f"business flow {name}", schema=schema_definition(name)
|
|
@@ -3,6 +3,7 @@ from __future__ import annotations
|
|
|
3
3
|
import hashlib
|
|
4
4
|
import json
|
|
5
5
|
import re
|
|
6
|
+
from collections import Counter
|
|
6
7
|
from dataclasses import asdict, replace
|
|
7
8
|
from datetime import datetime, timezone
|
|
8
9
|
from pathlib import Path
|
|
@@ -27,6 +28,7 @@ from .contracts import (
|
|
|
27
28
|
SourceSnapshot,
|
|
28
29
|
artifact_path,
|
|
29
30
|
now_iso,
|
|
31
|
+
prompt_schema,
|
|
30
32
|
read_artifact,
|
|
31
33
|
schema_definition,
|
|
32
34
|
write_artifact,
|
|
@@ -40,11 +42,14 @@ from .source import (
|
|
|
40
42
|
validate_evidence,
|
|
41
43
|
)
|
|
42
44
|
from .store import (
|
|
45
|
+
conflict_groups,
|
|
43
46
|
contribute_knowledge,
|
|
44
47
|
query_knowledge,
|
|
45
48
|
read_shared_knowledge,
|
|
46
49
|
record_task_execution,
|
|
47
50
|
resolve_conflicts,
|
|
51
|
+
split_by_focus,
|
|
52
|
+
task_focus,
|
|
48
53
|
validate_resolutions,
|
|
49
54
|
)
|
|
50
55
|
|
|
@@ -298,7 +303,9 @@ def _validate_fact_evidence(
|
|
|
298
303
|
"confirmed business claims require inspected code evidence"
|
|
299
304
|
)
|
|
300
305
|
for evidence in fact["evidence"]:
|
|
301
|
-
evidence["excerpt"] = validate_evidence(
|
|
306
|
+
evidence["excerpt"], evidence["line"], evidence["endLine"] = validate_evidence(
|
|
307
|
+
evidence, projects
|
|
308
|
+
)
|
|
302
309
|
if evidence["projectId"] not in result["inspectedProjects"]:
|
|
303
310
|
raise BusinessFlowError(
|
|
304
311
|
"claim evidence references an uninspected candidate"
|
|
@@ -379,7 +386,7 @@ def _instructions(
|
|
|
379
386
|
request: FlowRequest, execution: FlowExecution, baseline: FlowExecution | None
|
|
380
387
|
) -> str:
|
|
381
388
|
context = _investigation_context(request, execution, baseline)
|
|
382
|
-
schema =
|
|
389
|
+
schema = prompt_schema("result")
|
|
383
390
|
return "\n".join(
|
|
384
391
|
[
|
|
385
392
|
"# Business Flow Investigation",
|
|
@@ -395,12 +402,15 @@ def _instructions(
|
|
|
395
402
|
"For post mode, use the supplied project-specific baseline. Never invent missing before-state. Describe the actual delta and distinguish confirmed side effects from risks.",
|
|
396
403
|
"For contribute mode, extract newly observed business facts from the supplied validated task record and inspect source to confirm them. Empty facts are valid. Do not copy the report narrative as established truth.",
|
|
397
404
|
"For reconcile mode, reinspect every conflicting source and condition. Return explicit resolutions only with evidence-backed reasoning and original claimIds/acceptedClaimId. Preserve genuinely unresolved policy decisions in questions. Other modes return resolutions=[].",
|
|
405
|
+
"knowledge.conflictGroups lists each active conflict: the claims that disagree on one key at one source version. A resolution's claimIds must be exactly one group's claimIds, never claims of the same key from another group, and acceptedClaimId one of them. Resolve only groups whose freshness is current; a historical group's source has changed since and stays a conflict. Return the accepted claim's key, value and level unchanged as a fact with evidence you reinspected.",
|
|
406
|
+
"Stored knowledge claims cite evidence as projectId:path:line-endLine. knowledge.notShown counts, by business, stored claims that do not mention this task; look one up with `okstra explain-flow knowledge --query <business question>` when it applies.",
|
|
398
407
|
"Keep fact keys, business identifiers and fact values canonical in English; preserve original business terms in aliases. Do not create conflicts by translating the same fact. Read source evidence before accepting stored knowledge, including other projects' claims.",
|
|
399
408
|
"execution-verified requires a supplied JSON verificationReceipt with command, startedAt, endedAt, exitCode=0, output and matching projectId-to-digest sourceStates. A final report alone is not an execution receipt.",
|
|
409
|
+
'Each terms item has exactly two fields: {"term": "<business term>", "meaning": "<what it means here>"}.',
|
|
400
410
|
f"Write report titles, summaries, terms, steps, relationship data, gaps and questions in {request.report_language}; preserve paths, identifiers and enum values.",
|
|
401
411
|
"",
|
|
402
412
|
"## Source Material and Captured Baseline",
|
|
403
|
-
json.dumps(context, ensure_ascii=False,
|
|
413
|
+
json.dumps(context, ensure_ascii=False, separators=(",", ":")),
|
|
404
414
|
"",
|
|
405
415
|
"## Result Schema",
|
|
406
416
|
json.dumps(schema, ensure_ascii=False, indent=2),
|
|
@@ -412,6 +422,7 @@ def _instructions(
|
|
|
412
422
|
def _investigation_context(
|
|
413
423
|
request: FlowRequest, execution: FlowExecution, baseline: FlowExecution | None
|
|
414
424
|
) -> dict[str, Any]:
|
|
425
|
+
knowledge = _investigation_knowledge(request)
|
|
415
426
|
compact = [
|
|
416
427
|
{
|
|
417
428
|
"projectId": row["projectId"],
|
|
@@ -441,13 +452,65 @@ def _investigation_context(
|
|
|
441
452
|
)
|
|
442
453
|
if baseline
|
|
443
454
|
else "",
|
|
444
|
-
"knowledge":
|
|
445
|
-
|
|
446
|
-
|
|
447
|
-
|
|
448
|
-
|
|
449
|
-
|
|
450
|
-
|
|
455
|
+
"knowledge": {**knowledge, "claims": [_prompt_claim(row) for row in knowledge["claims"]]},
|
|
456
|
+
}
|
|
457
|
+
|
|
458
|
+
|
|
459
|
+
_PROMPT_CLAIM_FIELDS = ("id", "key", "business", "value", "level", "status", "freshness")
|
|
460
|
+
|
|
461
|
+
|
|
462
|
+
def _prompt_claim(row: dict[str, Any]) -> dict[str, Any]:
|
|
463
|
+
"""The investigator re-reads a claim's source before relying on it, so the
|
|
464
|
+
producers, source states and evidence excerpts stay in the store."""
|
|
465
|
+
claim = {field: row[field] for field in _PROMPT_CLAIM_FIELDS}
|
|
466
|
+
claim.update({field: row[field] for field in ("aliases", "relatedKeys") if row.get(field)})
|
|
467
|
+
claim["evidence"] = [
|
|
468
|
+
f"{item['projectId']}:{item['path']}:{item['line']}-{item['endLine']}"
|
|
469
|
+
for item in row["evidence"]
|
|
470
|
+
]
|
|
471
|
+
return claim
|
|
472
|
+
|
|
473
|
+
|
|
474
|
+
def _investigation_knowledge(request: FlowRequest) -> dict[str, Any]:
|
|
475
|
+
"""Stored claims for an investigation.
|
|
476
|
+
|
|
477
|
+
A task's question is its whole brief, whose words select nearly every stored
|
|
478
|
+
claim, so a task investigation keeps the claims that mention the task's
|
|
479
|
+
focus terms and counts the rest by business. A reconcile question names
|
|
480
|
+
its conflict keys and is not narrowed; it also gets the conflict groups,
|
|
481
|
+
because a resolution must cover exactly one and the claims no longer carry
|
|
482
|
+
the source versions that tell the groups apart.
|
|
483
|
+
"""
|
|
484
|
+
result = query_knowledge(
|
|
485
|
+
request.project_root,
|
|
486
|
+
request.question,
|
|
487
|
+
request.source_root,
|
|
488
|
+
request.project_group,
|
|
489
|
+
members_only=request.mode != "reconcile",
|
|
490
|
+
)
|
|
491
|
+
claims = result["claims"]
|
|
492
|
+
if request.mode == "reconcile":
|
|
493
|
+
return {
|
|
494
|
+
"claims": claims,
|
|
495
|
+
"conflictGroups": [
|
|
496
|
+
{
|
|
497
|
+
"key": group[0]["key"],
|
|
498
|
+
"freshness": group[0]["freshness"],
|
|
499
|
+
"claimIds": sorted(row["id"] for row in group),
|
|
500
|
+
}
|
|
501
|
+
for group in conflict_groups(claims)
|
|
502
|
+
],
|
|
503
|
+
"notShown": {},
|
|
504
|
+
"errors": result["errors"],
|
|
505
|
+
}
|
|
506
|
+
focus = task_focus(request.task_key, request.question) if request.task_key else ()
|
|
507
|
+
if not focus:
|
|
508
|
+
return {"claims": claims, "notShown": {}, "errors": result["errors"]}
|
|
509
|
+
focused, others = split_by_focus(claims, focus)
|
|
510
|
+
return {
|
|
511
|
+
"claims": focused,
|
|
512
|
+
"notShown": dict(Counter(row["business"] for row in others).most_common()),
|
|
513
|
+
"errors": result["errors"],
|
|
451
514
|
}
|
|
452
515
|
|
|
453
516
|
|
|
@@ -456,16 +519,7 @@ def _reinvestigate_conflicts(
|
|
|
456
519
|
) -> None:
|
|
457
520
|
if request.mode == "reconcile":
|
|
458
521
|
return
|
|
459
|
-
conflict_keys =
|
|
460
|
-
row["key"]
|
|
461
|
-
for row in query_knowledge(
|
|
462
|
-
request.project_root,
|
|
463
|
-
request.question,
|
|
464
|
-
request.source_root,
|
|
465
|
-
request.project_group,
|
|
466
|
-
)["claims"]
|
|
467
|
-
if row["status"] == "conflict"
|
|
468
|
-
}
|
|
522
|
+
conflict_keys = _conflict_keys(request, execution)
|
|
469
523
|
if not conflict_keys:
|
|
470
524
|
return
|
|
471
525
|
child = explain_flow(
|
|
@@ -483,25 +537,29 @@ def _reinvestigate_conflicts(
|
|
|
483
537
|
"error": child.get("error", ""),
|
|
484
538
|
"questions": child.get("result", {}).get("questions", []),
|
|
485
539
|
}
|
|
486
|
-
unresolved =
|
|
487
|
-
row["key"]
|
|
488
|
-
for row in query_knowledge(
|
|
489
|
-
request.project_root,
|
|
490
|
-
request.question,
|
|
491
|
-
request.source_root,
|
|
492
|
-
request.project_group,
|
|
493
|
-
)["claims"]
|
|
494
|
-
if row["status"] == "conflict"
|
|
495
|
-
]
|
|
540
|
+
unresolved = _conflict_keys(request, execution)
|
|
496
541
|
if unresolved:
|
|
497
542
|
execution["result"]["questions"].append(
|
|
498
|
-
"Unresolved shared business conflicts: "
|
|
499
|
-
+ ", ".join(sorted(set(unresolved)))
|
|
543
|
+
"Unresolved shared business conflicts: " + ", ".join(sorted(unresolved))
|
|
500
544
|
)
|
|
501
545
|
execution["status"] = "partial"
|
|
502
546
|
write_artifact(path, execution, "execution")
|
|
503
547
|
|
|
504
548
|
|
|
549
|
+
def _conflict_keys(request: FlowRequest, execution: FlowExecution) -> set[str]:
|
|
550
|
+
"""Conflicts this explanation answers for: among the claims its investigator
|
|
551
|
+
was shown, and on a key it returned, which is where a conflict it created
|
|
552
|
+
lies even when the claim does not mention the task."""
|
|
553
|
+
returned = {fact["key"] for fact in execution["result"]["facts"]}
|
|
554
|
+
shown = _investigation_knowledge(request)["claims"]
|
|
555
|
+
stored = read_shared_knowledge(request.project_root, request.project_group)["claims"]
|
|
556
|
+
return {
|
|
557
|
+
row["key"]
|
|
558
|
+
for row in [*shown, *(row for row in stored if row["key"] in returned)]
|
|
559
|
+
if row["status"] == "conflict"
|
|
560
|
+
}
|
|
561
|
+
|
|
562
|
+
|
|
505
563
|
def load_execution(project_root: Path, execution_id: str) -> FlowExecution:
|
|
506
564
|
if not execution_id or any(
|
|
507
565
|
char not in "abcdefghijklmnopqrstuvwxyz0123456789-" for char in execution_id
|
|
@@ -17,7 +17,7 @@ from .contracts import (
|
|
|
17
17
|
from .engine import explain_flow, load_execution
|
|
18
18
|
from .invocation import FlowExecutor
|
|
19
19
|
from .source import candidate_projects, capture_projects, changed_projects
|
|
20
|
-
from .store import knowledge_packet, read_task_links, record_task_execution
|
|
20
|
+
from .store import knowledge_packet, read_task_links, record_task_execution, task_focus
|
|
21
21
|
|
|
22
22
|
|
|
23
23
|
def prepare_task_knowledge(
|
|
@@ -58,7 +58,9 @@ def prepare_task_knowledge(
|
|
|
58
58
|
_ensure_pre_explanation(project_root, request, executor)
|
|
59
59
|
except (OSError, ValueError, JsonBoundaryError) as exc:
|
|
60
60
|
return f"## Shared Business Knowledge\n\nBusiness preparation failed: {exc}\n"
|
|
61
|
-
return knowledge_packet(
|
|
61
|
+
return knowledge_packet(
|
|
62
|
+
project_root, question, Path(source), task_focus(str(ctx.get("TASK_KEY", "")), question)
|
|
63
|
+
)
|
|
62
64
|
|
|
63
65
|
|
|
64
66
|
def _flow_request(
|
|
@@ -168,7 +168,12 @@ def capture_projects(candidates: list[ProjectCandidate]) -> list[SourceSnapshot]
|
|
|
168
168
|
|
|
169
169
|
def validate_evidence(
|
|
170
170
|
evidence: BusinessEvidence, projects: list[SourceSnapshot]
|
|
171
|
-
) -> str:
|
|
171
|
+
) -> tuple[str, int, int]:
|
|
172
|
+
"""The source lines that hold the excerpt, and their range.
|
|
173
|
+
|
|
174
|
+
The range is the cited one, or the nearest one within two lines that holds
|
|
175
|
+
the excerpt.
|
|
176
|
+
"""
|
|
172
177
|
project = next(
|
|
173
178
|
(row for row in projects if row["projectId"] == evidence["projectId"]), None
|
|
174
179
|
)
|
|
@@ -190,15 +195,42 @@ def validate_evidence(
|
|
|
190
195
|
start, end = evidence["line"], evidence["endLine"]
|
|
191
196
|
if end < start or end > len(lines):
|
|
192
197
|
raise BusinessFlowError("evidence line range is invalid")
|
|
193
|
-
|
|
194
|
-
|
|
195
|
-
|
|
196
|
-
|
|
197
|
-
|
|
198
|
-
|
|
198
|
+
if not _excerpt_matches(evidence["excerpt"], lines[start - 1 : end]):
|
|
199
|
+
located = _nearby_range(evidence["excerpt"], lines, start, end)
|
|
200
|
+
if located is None:
|
|
201
|
+
raise BusinessFlowError(
|
|
202
|
+
f"evidence excerpt does not match source: {evidence['path']}:{start}"
|
|
203
|
+
)
|
|
204
|
+
start, end = located
|
|
205
|
+
return "\n".join(lines[start - 1 : end]), start, end
|
|
199
206
|
|
|
200
207
|
|
|
201
208
|
_ELISION_MARKERS = {"...", "\u2026"}
|
|
209
|
+
_LINE_DRIFT = 2
|
|
210
|
+
|
|
211
|
+
|
|
212
|
+
def _nearby_range(
|
|
213
|
+
excerpt: str, lines: list[str], start: int, end: int
|
|
214
|
+
) -> tuple[int, int] | None:
|
|
215
|
+
"""The shortest, then closest, range within two lines of the cited one that
|
|
216
|
+
holds the excerpt.
|
|
217
|
+
|
|
218
|
+
Investigators copy the right lines but often count the range a line off. A
|
|
219
|
+
wider range also holds the excerpt, so the shortest one is where it is.
|
|
220
|
+
"""
|
|
221
|
+
candidates = sorted(
|
|
222
|
+
(last - first, abs(first - start) + abs(last - end), first, last)
|
|
223
|
+
for first in range(max(1, start - _LINE_DRIFT), start + _LINE_DRIFT + 1)
|
|
224
|
+
for last in range(max(first, end - _LINE_DRIFT), min(len(lines), end + _LINE_DRIFT) + 1)
|
|
225
|
+
)
|
|
226
|
+
return next(
|
|
227
|
+
(
|
|
228
|
+
(first, last)
|
|
229
|
+
for _, _, first, last in candidates
|
|
230
|
+
if _excerpt_matches(excerpt, lines[first - 1 : last])
|
|
231
|
+
),
|
|
232
|
+
None,
|
|
233
|
+
)
|
|
202
234
|
|
|
203
235
|
|
|
204
236
|
def _excerpt_matches(excerpt: str, source: list[str]) -> bool:
|