Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(compile): 由 OV 托管外部任务生命周期 (#4436)

Qin Haojieb6af3d4bfcdf
diff --git a/bot/tests/test_compile.py b/bot/tests/test_compile.py
index facc5bfa6..c2214ea25 100644
--- a/bot/tests/test_compile.py
+++ b/bot/tests/test_compile.py
@@ -40,7 +40,6 @@ from vikingbot.compile.readlist import (
ReadTrackingTool,
)
from vikingbot.compile.renderer import (
- RenderedBundle,
WikiRenderer,
wiki_page_path_from_title,
)
@@ -143,8 +142,6 @@ def test_compile_limit_defaults_match_the_resource_envelope():
assert limits.concurrent_tasks == 10
assert limits.accepted_tasks == 40
assert limits.accepted_tasks_per_principal == 10
- assert limits.queue_wait_seconds == 60 * 60
- assert limits.task_runtime_seconds == 60 * 60
assert limits.agent_iterations == 60
assert limits.source_files == 5000
assert limits.source_total_bytes == 1024 * 1024 * 1024
@@ -158,30 +155,6 @@ def test_compile_limit_defaults_match_the_resource_envelope():
assert limits.output_operations == 256
assert DirectBackendConfig().allow_compile_exec is True
-
-def test_compile_request_schema_defers_runtime_max_but_requires_positive_finite_seconds():
- request = CompileRequest.model_validate(
- {
- "from": ["viking://resources/source"],
- "to": "viking://resources/wiki",
- "skill": "viking://agent/skills/wiki",
- "runtime_timeout_seconds": 24 * 60 * 60,
- }
- )
- assert request.runtime_timeout_seconds == 24 * 60 * 60
-
- for invalid in (0, float("inf"), float("nan")):
- with pytest.raises(ValueError):
- CompileRequest.model_validate(
- {
- "from": ["viking://resources/source"],
- "to": "viking://resources/wiki",
- "skill": "viking://agent/skills/wiki",
- "runtime_timeout_seconds": invalid,
- }
- )
-
-
def test_wiki_page_requires_exactly_one_body_source():
body = _page(1, "One")
body.pop("body_markdown")
@@ -3055,7 +3028,6 @@ async def test_request_normalization_uses_default_reason_and_canonical_skill(mon
"to": "viking://resources/wiki",
"skill": "viking://agent/skills/wiki/SKILL.md",
"reason": " ",
- "runtime_timeout_seconds": 20 * 60,
}
),
connection={"api_key": "secret"},
@@ -3065,7 +3037,6 @@ async def test_request_normalization_uses_default_reason_and_canonical_skill(mon
assert normalized.skill == "viking://agent/skills/wiki"
assert normalized.reason == DEFAULT_COMPILE_REASON
assert normalized.reason_provided is False
- assert normalized.runtime_timeout_seconds == 20 * 60
Client.created.clear()
Client.skill_content = "---\nname: wiki\n---\nCompile it"
@@ -3083,35 +3054,6 @@ async def test_request_normalization_uses_default_reason_and_canonical_skill(mon
assert raised.value.code == "SKILL_INVALID"
assert Client.created == set()
-
-async def test_request_normalization_rejects_runtime_above_server_limit_before_io(monkeypatch):
- async def create_client(**kwargs):
- raise AssertionError(f"client must not be created: {kwargs}")
-
- monkeypatch.setattr("vikingbot.compile.service.VikingClient.create", create_client)
- service = object.__new__(BotCompileService)
- service.config = None
- service.limits = CompileLimits(task_runtime_seconds=10)
-
- with pytest.raises(CompileFailure) as raised:
- await service._normalize_request(
- CompileRequest.model_validate(
- {
- "from": ["viking://resources/source"],
- "to": "viking://resources/wiki",
- "skill": "viking://agent/skills/wiki",
- "runtime_timeout_seconds": 11,
- }
- ),
- connection={"api_key": "secret"},
- )
-
- assert raised.value.code == "RESOURCE_EXHAUSTED"
- assert raised.value.stage == "queued"
- assert "server limit of 10 seconds" in str(raised.value)
-
-
def test_compile_target_accepts_only_exact_skill_namespaces():
directory = {"isDir": True}
@@ -4408,10 +4350,18 @@ async def test_compile_create_task_connection_and_exec(
accepted = await service.create_task(
_compile_request(connection=with_connection),
principal_scope=principal_scope,
+ task_id="cmp_ov_task",
)
await started.wait()
+ repeated = await service.create_task(
+ _compile_request(connection=with_connection),
+ principal_scope=principal_scope,
+ task_id="cmp_ov_task",
+ )
assert accepted.status == "accepted"
+ assert accepted.session_id == "cmp_ov_task"
+ assert repeated.session_id == accepted.session_id
assert service._compile_capabilities().exec_enabled is expected_exec
expected_connection = {"api_key": "secret"} if with_connection else {}
assert observed == {
@@ -4516,75 +4466,7 @@ async def test_compile_admission_is_bounded_per_principal_and_globally(monkeypat
@pytest.mark.asyncio
-async def test_compile_queue_wait_has_a_deadline(tmp_path: Path):
- service = _compile_service(
- tmp_path,
- auth_mode="api_key",
- backend=SandboxBackend.AIOSANDBOX,
- limits=CompileLimits(concurrent_tasks=1, queue_wait_seconds=0.01),
- )
- request = _sanitized_compile_request()
- task = CompileTask(
- task_id="cmp_queued",
- principal_scope="owner",
- sanitized_request=request,
- status="accepted",
- stage="queued",
- created_at=utc_now(),
- updated_at=utc_now(),
- )
- await service.store.create(task)
- await service._semaphore.acquire()
- try:
- await service._run_task(task.task_id, request, {"api_key": "secret"})
- finally:
- service._semaphore.release()
-
- failed = await service.store.get(task.task_id)
- assert failed is not None
- assert failed.status == "failed"
- assert failed.stage == "queued"
- assert failed.error is not None
- assert failed.error.code == "DEADLINE_EXCEEDED"
- assert service._target_locks == {}
-
-
-async def test_compile_uses_request_runtime_timeout(monkeypatch, tmp_path: Path):
- service = _compile_service(
- tmp_path,
- auth_mode="api_key",
- backend=SandboxBackend.AIOSANDBOX,
- )
- request = _sanitized_compile_request().model_copy(update={"runtime_timeout_seconds": 0.01})
- task = CompileTask(
- task_id="cmp_runtime",
- principal_scope="owner",
- sanitized_request=request,
- status="accepted",
- stage="queued",
- created_at=utc_now(),
- updated_at=utc_now(),
- )
- await service.store.create(task)
- observed = []
-
- async def execute(*args, runtime_deadline, **kwargs):
- del args, kwargs
- observed.append(runtime_deadline - asyncio.get_running_loop().time())
- await asyncio.Event().wait()
-
- monkeypatch.setattr(service, "_execute_task", execute)
- await service._run_task(task.task_id, request, {"api_key": "secret"})
-
- failed = await service.store.get(task.task_id)
- assert observed and 0 < observed[0] <= 0.02
- assert failed is not None and failed.status == "failed"
- assert failed.error is not None and failed.error.code == "DEADLINE_EXCEEDED"
-
-
-async def test_timeout_salvage_copies_workspace_and_repairs_links(tmp_path: Path):
+async def test_salvage_copies_workspace_and_repairs_links(tmp_path: Path):
service = _compile_service(
tmp_path,
auth_mode="api_key",
@@ -4711,7 +4593,7 @@ async def test_timeout_salvage_copies_workspace_and_repairs_links(tmp_path: Path
"[Missing](missing(1).md)",
],
)
-def test_timeout_salvage_removes_unresolved_complex_markdown_links(content: str):
+def test_salvage_removes_unresolved_complex_markdown_links(content: str):
assert (
BotCompileService._repair_salvaged_markdown(
content,
@@ -4722,7 +4604,7 @@ def test_timeout_salvage_removes_unresolved_complex_markdown_links(content: str)
)
-def test_timeout_salvage_preserves_existing_escaped_parenthesis_link():
+def test_salvage_preserves_existing_escaped_parenthesis_link():
content = r"[Paren](../meta/foo\(1\).md)"
assert (
@@ -4736,7 +4618,7 @@ def test_timeout_salvage_preserves_existing_escaped_parenthesis_link():
@pytest.mark.asyncio
-async def test_timeout_salvage_ignores_preexisting_srt_settings(tmp_path: Path):
+async def test_salvage_ignores_preexisting_srt_settings(tmp_path: Path):
service = _compile_service(
tmp_path,
auth_mode="api_key",
@@ -4787,7 +4669,7 @@ async def test_srt_settings_created_by_manager_are_in_the_workspace_baseline(
@pytest.mark.asyncio
-async def test_timeout_salvage_skips_oversized_file_before_reading(tmp_path: Path):
+async def test_salvage_skips_oversized_file_before_reading(tmp_path: Path):
limits = CompileLimits(output_total_bytes=4)
service = _compile_service(
tmp_path,
@@ -4845,7 +4727,7 @@ async def test_timeout_salvage_skips_oversized_file_before_reading(tmp_path: Pat
@pytest.mark.asyncio
-async def test_timeout_salvage_grace_returns_when_cancellation_is_suppressed(
+async def test_salvage_grace_returns_when_cancellation_is_suppressed(
monkeypatch, tmp_path: Path
):
service = _compile_service(
@@ -4888,12 +4770,12 @@ async def test_timeout_salvage_grace_returns_when_cancellation_is_suppressed(
request=request,
sandbox=object(),
workspace_baseline=set(),
- reason="reached its runtime deadline",
- failure_code="DEADLINE_EXCEEDED",
+ reason="reached its iteration limit",
+ failure_code="AGENT_OUTPUT_INVALID",
),
timeout=0.2,
)
- assert raised.value.code == "DEADLINE_EXCEEDED"
+ assert raised.value.code == "AGENT_OUTPUT_INVALID"
assert raised.value.stage == "salvaging"
assert "grace limit" in str(raised.value)
assert loop.time() - started_at < 0.2
@@ -4904,7 +4786,7 @@ async def test_timeout_salvage_grace_returns_when_cancellation_is_suppressed(
@pytest.mark.asyncio
-async def test_salvage_keeps_its_grace_period_when_parent_runtime_expires(
+async def test_salvage_keeps_its_grace_period_when_parent_is_cancelled(
monkeypatch, tmp_path: Path
):
service = _compile_service(
@@ -4968,7 +4850,6 @@ async def test_cleanup_grace_releases_execution_slot_and_target_lock(tmp_path: P
limits=CompileLimits(
concurrent_tasks=1,
cleanup_grace_seconds=0.01,
- task_runtime_seconds=1,
),
)
request = _sanitized_compile_request()
@@ -4989,8 +4870,8 @@ async def test_cleanup_grace_releases_execution_slot_and_target_lock(tmp_path: P
await release_cleanup.wait()
cleanup_finished.set()
- async def execute(task_id, _request, connection, *, runtime_deadline):
- del connection, runtime_deadline
+ async def execute(task_id, _request, connection):
+ del connection
if task_id == "cmp_first":
await service._cleanup_execution_resources(
sandbox_manager=StubbornManager(),
@@ -5017,7 +4898,7 @@ async def test_cleanup_grace_releases_execution_slot_and_target_lock(tmp_path: P
@pytest.mark.asyncio
-async def test_timeout_salvage_respects_combined_output_operation_limit(tmp_path: Path):
+async def test_salvage_respects_combined_output_operation_limit(tmp_path: Path):
limits = CompileLimits(output_pages=2, output_files=2, output_operations=3)
service = _compile_service(
tmp_path,
@@ -5062,10 +4943,7 @@ async def test_timeout_salvage_respects_combined_output_operation_limit(tmp_path
@pytest.mark.asyncio
[email protected]("cutoff", ["runtime", "iterations", "accepted", "writing"])
-async def test_compile_cutoff_salvages_before_workspace_cleanup(
- monkeypatch, tmp_path: Path, cutoff: str
-):
+async def test_iteration_limit_salvages_before_workspace_cleanup(monkeypatch, tmp_path: Path):
observed = []
remote_files = {}
@@ -5123,28 +5001,7 @@ async def test_compile_cutoff_salvages_before_workspace_cleanup(
async def run_structured_task(self, **kwargs):
del kwargs
remote_files["output.md"] = b"partial"
- if cutoff == "iterations":
- raise AgentIterationLimitExceeded(1)
- if cutoff == "accepted":
- submit_tool.bundle = WikiBundleDraft.model_validate({"pages": []})
- await asyncio.Event().wait()
- if cutoff == "writing":
- return (
- RenderedBundle(
- operations=[
- {
- "uri": "viking://resources/wiki/guide.md",
- "content": "Guide",
- "mode": "upsert",
- }
- ],
- created=["viking://resources/wiki/guide.md"],
- ),
- [],
- {},
- 1,
- )
- await asyncio.Event().wait()
+ raise AgentIterationLimitExceeded(1)
class Client:
async def get_skill(self, skill_name, *, target_uri):
@@ -5156,12 +5013,6 @@ async def test_compile_cutoff_salvages_before_workspace_cleanup(
"files": [],
}
- async def batch_write(self, **kwargs):
- assert cutoff == "writing"
- assert kwargs["operations"][0]["uri"] == "viking://resources/wiki/guide.md"
- assert kwargs["wait"] is False
- await asyncio.Event().wait()
-
async def close(self):
return None
@@ -5185,7 +5036,7 @@ async def test_compile_cutoff_salvages_before_workspace_cleanup(
assert workspace_baseline == set()
assert request.to == "viking://resources/wiki"
assert await sandbox.read_file_bytes("output.md") == b"partial"
- assert ("runtime deadline" if cutoff == "runtime" else "1-iteration limit") in reason
+ assert "1-iteration limit" in reason
observed.append("salvage")
return CompileResult(
**{
@@ -5230,7 +5081,7 @@ async def test_compile_cutoff_salvages_before_workspace_cleanup(
request = _sanitized_compile_request()
task = CompileTask(
- task_id=f"cmp_{cutoff}",
+ task_id="cmp_iterations",
principal_scope="owner",
sanitized_request=request,
status="accepted",
@@ -5239,30 +5090,10 @@ async def test_compile_cutoff_salvages_before_workspace_cleanup(
updated_at=utc_now(),
)
await service.store.create(task)
- loop = asyncio.get_running_loop()
- execute = service._execute_task(
- task.task_id,
- request,
- {"api_key": "secret"},
- runtime_deadline=loop.time()
- + (0.01 if cutoff in {"runtime", "accepted", "writing"} else 60),
- )
- if cutoff in {"accepted", "writing"}:
- with pytest.raises(asyncio.TimeoutError):
- await asyncio.wait_for(execute, timeout=0.01)
- elif cutoff == "runtime":
- await asyncio.wait_for(execute, timeout=0.01)
- else:
- await execute
+ await service._execute_task(task.task_id, request, {"api_key": "secret"})
completed = await service.store.get(task.task_id)
assert completed is not None
- if cutoff in {"accepted", "writing"}:
- assert completed.status == ("committing" if cutoff == "writing" else "running")
- assert completed.stage == cutoff.replace("accepted", "agent")
- assert completed.result is None
- assert observed == ["cleanup"]
- return
assert completed.status == "completed"
assert completed.stage == "salvaged"
assert completed.result is not None
diff --git a/bot/tests/test_openapi_auth.py b/bot/tests/test_openapi_auth.py
index 8d866c3d6..567b1d6fb 100644
--- a/bot/tests/test_openapi_auth.py
+++ b/bot/tests/test_openapi_auth.py
@@ -36,6 +36,7 @@ def message_bus():
def _make_client(channel: OpenAPIChannel) -> TestClient:
app = FastAPI()
app.include_router(channel.get_router(), prefix="/bot/v1")
+ app.include_router(channel.get_gateway_router())
return TestClient(app)
@@ -57,10 +58,16 @@ class TestOpenAPIAuth:
class FakeCompileService:
def __init__(self):
self.scope = None
+ self.idempotency_key = None
- async def create_task(self, request, *, principal_scope):
+ async def create_task(self, request, *, principal_scope, task_id=None):
self.scope = principal_scope
- return CompileAccepted(task_id="cmp_test", to=request.to)
+ self.idempotency_key = task_id
+ return CompileAccepted(
+ session_id="cmp_test",
+ task_id="cmp_test",
+ to=request.to,
+ )
async def get_task(self, task_id, *, principal_scope):
if task_id != "cmp_test" or principal_scope != self.scope:
@@ -88,21 +95,51 @@ class TestOpenAPIAuth:
compile_service=service,
)
client = _make_client(channel)
- created = client.post(
- "/bot/v1/compile",
- json={
+ request_body = {
+ "task_type": "compile",
+ "payload": {
"from": ["viking://resources/source"],
"to": "viking://resources/wiki",
"skill": "viking://agent/skills/wiki",
},
+ }
+ unsupported = client.post(
+ "/runtime/v1/tasks",
+ json={**request_body, "task_type": "chat"},
+ )
+ assert unsupported.status_code == 422
+ invalid_payload = client.post(
+ "/runtime/v1/tasks",
+ json={**request_body, "payload": {**request_body["payload"], "skill": ""}},
+ )
+ assert invalid_payload.status_code == 422
+ assert service.scope is None
+ created = client.post(
+ "/runtime/v1/tasks",
+ headers={"Idempotency-Key": "cmp_test"},
+ json=request_body,
)
assert created.status_code == 202
+ assert created.json()["session_id"] == "cmp_test"
assert created.json()["task_id"] == "cmp_test"
+ assert service.idempotency_key == "cmp_test"
assert client.get("/bot/v1/compile/cmp_test").status_code == 200
assert client.get("/bot/v1/compile/cmp_other").status_code == 404
+ status_response = client.post(
+ "/runtime/v1/tasks/status",
+ json={"session_id": "cmp_test"},
+ )
+ assert status_response.status_code == 200
+ assert status_response.json()["stage"] == "compile: agent"
cancelled = client.post("/bot/v1/compile/cmp_test/cancel")
assert cancelled.status_code == 200
assert cancelled.json()["status"] == "cancelled"
+ session_cancelled = client.post(
+ "/runtime/v1/tasks/cancel",
+ json={"session_id": "cmp_test"},
+ )
+ assert session_cancelled.status_code == 200
+ assert session_cancelled.json()["status"] == "cancelled"
assert client.post("/bot/v1/compile/cmp_other/cancel").status_code == 404
def test_dev_compile_with_forwarded_connection_uses_same_principal_for_status(
@@ -113,10 +150,15 @@ class TestOpenAPIAuth:
self.scope = None
self.connection = "unset"
- async def create_task(self, request, *, principal_scope):
+ async def create_task(self, request, *, principal_scope, task_id=None):
+ assert task_id is None
self.scope = principal_scope
self.connection = request.openviking_connection
- return CompileAccepted(task_id="cmp_dev", to=request.to)
+ return CompileAccepted(
+ session_id="cmp_dev",
+ task_id="cmp_dev",
+ to=request.to,
+ )
async def get_task(self, task_id, *, principal_scope):
if task_id != "cmp_dev" or principal_scope != self.scope:
@@ -154,6 +196,7 @@ class TestOpenAPIAuth:
monkeypatch.setattr(channel, "_assert_runtime_upstream_auth_mode", fake_runtime_probe)
app = FastAPI()
app.include_router(channel.get_router(), prefix="/bot/v1")
+ app.include_router(channel.get_gateway_router())
client = TestClient(app, client=("127.0.0.1", 50000))
headers = {
"X-Gateway-Token": "gateway-secret",
@@ -163,21 +206,28 @@ class TestOpenAPIAuth:
}
created = client.post(
- "/bot/v1/compile",
+ "/runtime/v1/tasks",
headers=headers,
json={
- "from": ["viking://resources/source"],
- "to": "viking://resources/wiki",
- "skill": "viking://agent/skills/wiki",
- "openviking_connection": {
- "api_key": "stale-dev-key",
- "account_id": "default",
- "user_id": "default",
- "server_url": "http://127.0.0.1:1933",
+ "task_type": "compile",
+ "payload": {
+ "from": ["viking://resources/source"],
+ "to": "viking://resources/wiki",
+ "skill": "viking://agent/skills/wiki",
+ "openviking_connection": {
+ "api_key": "stale-dev-key",
+ "account_id": "default",
+ "user_id": "default",
+ "server_url": "http://127.0.0.1:1933",
+ },
},
},
)
- status_response = client.get("/bot/v1/compile/cmp_dev", headers=headers)
+ status_response = client.post(
+ "/runtime/v1/tasks/status",
+ headers=headers,
+ json={"session_id": "cmp_dev"},
+ )
assert created.status_code == 202
assert status_response.status_code == 200
diff --git a/bot/vikingbot/channels/openapi.py b/bot/vikingbot/channels/openapi.py
index 91e507a54..3033aadcf 100644
--- a/bot/vikingbot/channels/openapi.py
+++ b/bot/vikingbot/channels/openapi.py
@@ -572,6 +572,16 @@ class OpenAPIChannel(BaseChannel):
) -> GatewayRequestAuth:
return await channel._verify_gateway_request(http_request, x_gateway_token)
+ if channel._compile_service is not None:
+ from vikingbot.compile.router import register_runtime_task_routes
+
+ register_runtime_task_routes(
+ router,
+ channel=channel,
+ verify_gateway_request=verify_gateway_request,
+ service=channel._compile_service,
+ )
+
@router.get("/health")
async def gateway_health(
http_request: Request,
diff --git a/bot/vikingbot/compile/models.py b/bot/vikingbot/compile/models.py
index b4ed2af72..5aca18111 100644
--- a/bot/vikingbot/compile/models.py
+++ b/bot/vikingbot/compile/models.py
@@ -49,8 +49,6 @@ class CompileLimits(BaseModel):
concurrent_tasks: int = 10
accepted_tasks: int = 40
accepted_tasks_per_principal: int = 10
- queue_wait_seconds: float = 60 * 60
- task_runtime_seconds: float = 60 * 60
salvage_grace_seconds: float = 120
cleanup_grace_seconds: float = 40
terminal_task_retention_seconds: float = 24 * 60 * 60
@@ -64,11 +62,7 @@ class CompileRequest(BaseModel):
to: str = Field(min_length=1)
reason: str | None = None
skill: str = Field(min_length=1)
- runtime_timeout_seconds: float | None = Field(
- default=None,
- gt=0,
- allow_inf_nan=False,
- )
+ args: dict[str, Any] | None = None
openviking_connection: OpenVikingConnection | None = None
_principal_scope: str = PrivateAttr(default="local")
@@ -81,11 +75,6 @@ class SanitizedCompileRequest(BaseModel):
reason: str
reason_provided: bool = False
skill: str
- runtime_timeout_seconds: float | None = Field(
- default=None,
- gt=0,
- allow_inf_nan=False,
- )
class WikiPageDraft(BaseModel):
@@ -233,6 +222,7 @@ class CompileTask(BaseModel):
stage: str
created_at: str
updated_at: str
+ meta: dict[str, Any] = Field(default_factory=dict)
result: CompileResult | None = None
error: CompileErrorInfo | None = None
@@ -246,11 +236,18 @@ class CompileTask(BaseModel):
class CompileAccepted(BaseModel):
model_config = ConfigDict(extra="forbid")
+ session_id: str
task_id: str
status: Literal["accepted"] = "accepted"
to: str
+class CompileSessionRequest(BaseModel):
+ model_config = ConfigDict(extra="forbid")
+
+ session_id: str = Field(min_length=1)
+
+
class CompileFailure(RuntimeError):
def __init__(self, code: str, message: str, *, stage: str):
super().__init__(message)
@@ -270,6 +267,7 @@ __all__ = [
"CompileLimits",
"CompileRequest",
"CompileResult",
+ "CompileSessionRequest",
"CompileTask",
"DEFAULT_COMPILE_REASON",
"OKF_VERSION",
diff --git a/bot/vikingbot/compile/router.py b/bot/vikingbot/compile/router.py
index 21dd427b9..27cb1d2dd 100644
--- a/bot/vikingbot/compile/router.py
+++ b/bot/vikingbot/compile/router.py
@@ -2,13 +2,27 @@
from __future__ import annotations
-from typing import Any, Awaitable, Callable
+from typing import Any, Awaitable, Callable, Literal
-from fastapi import APIRouter, Depends, HTTPException, Request, status
+from fastapi import APIRouter, Depends, Header, HTTPException, Request, status
+from pydantic import BaseModel, ConfigDict
-from vikingbot.compile.models import CompileAccepted, CompileFailure, CompileRequest
+from vikingbot.compile.models import (
+ CompileAccepted,
+ CompileFailure,
+ CompileRequest,
+ CompileSessionRequest,
+)
from vikingbot.compile.service import BotCompileService
+
+class RuntimeTaskRequest(BaseModel):
+ model_config = ConfigDict(extra="forbid")
+
+ task_type: Literal["compile"]
+ payload: CompileRequest
+
+
_ERROR_HTTP_STATUS = {
"INVALID_ARGUMENT": status.HTTP_400_BAD_REQUEST,
"SKILL_INVALID": status.HTTP_400_BAD_REQUEST,
@@ -36,26 +50,7 @@ def register_compile_routes(
verify_gateway_request: Callable[..., Awaitable[Any]],
service: BotCompileService,
) -> None:
- """Attach compile endpoints while reusing OpenAPIChannel's auth dependency."""
-
- @router.post(
- "/compile",
- response_model=CompileAccepted,
- status_code=status.HTTP_202_ACCEPTED,
- )
- async def create_compile(
- compile_request: CompileRequest,
- http_request: Request,
- auth: Any = Depends(verify_gateway_request),
- ) -> CompileAccepted:
- await channel._prepare_compile_request(http_request, compile_request, auth)
- try:
- return await service.create_task(
- compile_request,
- principal_scope=compile_request._principal_scope,
- )
- except CompileFailure as exc:
- _raise_http_failure(exc)
+ """Attach the existing Bot task query and cancellation endpoints."""
@router.get("/compile/{task_id}")
async def get_compile(
@@ -88,4 +83,79 @@ def register_compile_routes(
return task
-__all__ = ["register_compile_routes"]
+def register_runtime_task_routes(
+ router: APIRouter,
+ *,
+ channel: Any,
+ verify_gateway_request: Callable[..., Awaitable[Any]],
+ service: BotCompileService,
+) -> None:
+ """Attach the Runtime task protocol using the existing Compile executor."""
+
+ @router.post(
+ "/runtime/v1/tasks",
+ response_model=CompileAccepted,
+ status_code=status.HTTP_202_ACCEPTED,
+ )
+ async def create_task(
+ body: RuntimeTaskRequest,
+ http_request: Request,
+ auth: Any = Depends(verify_gateway_request),
+ idempotency_key: str | None = Header(None, alias="Idempotency-Key"),
+ ) -> CompileAccepted:
+ await channel._prepare_compile_request(http_request, body.payload, auth)
+ try:
+ return await service.create_task(
+ body.payload,
+ principal_scope=body.payload._principal_scope,
+ task_id=idempotency_key,
+ )
+ except CompileFailure as exc:
+ _raise_http_failure(exc)
+
+ async def load_session(
+ body: CompileSessionRequest,
+ http_request: Request,
+ auth: Any,
+ *,
+ cancel: bool,
+ ) -> dict[str, Any]:
+ principal_scope = await channel._resolve_request_principal(http_request, auth)
+ if cancel:
+ task = await service.cancel_task(body.session_id, principal_scope=principal_scope)
+ else:
+ task = await service.get_task(body.session_id, principal_scope=principal_scope)
+ if task is None:
+ raise HTTPException(
+ status_code=status.HTTP_404_NOT_FOUND,
+ detail={"code": "NOT_FOUND", "message": "Compile session not found"},
+ )
+ task_status = str(task.get("status") or "running")
+ response: dict[str, Any] = {
+ "status": "pending" if task_status == "accepted" else task_status,
+ "stage": f"compile: {task.get('stage') or task_status}",
+ "error": task.get("error"),
+ "meta": task.get("meta") or {},
+ }
+ if task.get("result") is not None:
+ response["result"] = task["result"]
+ return response
+
+ @router.post("/runtime/v1/tasks/status")
+ async def get_compile_status(
+ body: CompileSessionRequest,
+ http_request: Request,
+ auth: Any = Depends(verify_gateway_request),
+ ) -> dict[str, Any]:
+ return await load_session(body, http_request, auth, cancel=False)
+
+ @router.post("/runtime/v1/tasks/cancel")
+ async def cancel_compile_session(
+ body: CompileSessionRequest,
+ http_request: Request,
+ auth: Any = Depends(verify_gateway_request),
+ ) -> dict[str, Any]:
+ return await load_session(body, http_request, auth, cancel=True)
+
+
+__all__ = ["register_compile_routes", "register_runtime_task_routes"]
diff --git a/bot/vikingbot/compile/service.py b/bot/vikingbot/compile/service.py
index b56248a7b..f4cf9cf9c 100644
--- a/bot/vikingbot/compile/service.py
+++ b/bot/vikingbot/compile/service.py
@@ -102,6 +102,8 @@ _LANGUAGE_CONTEXT_CHARS = 16_000
_COMPILE_BUDGET_REMINDER_THRESHOLDS = (15, 8, 3) # heads_up / warn / critical iterations left
_REQUIREMENT_NAME_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_.-]*$")
+
+
def _workspace_submission_rule(*, exec_enabled: bool) -> str:
"""How to hand over content too large to inline into submit_wiki_bundle."""
writer = "write_file or exec" if exec_enabled else "write_file"
@@ -380,8 +382,31 @@ class BotCompileService:
request: CompileRequest,
*,
principal_scope: str,
+ task_id: str | None = None,
) -> CompileAccepted:
await self.start()
+ if task_id is not None:
+ try:
+ existing = await self.store.get(task_id)
+ except ValueError as exc:
+ raise CompileFailure(
+ "INVALID_ARGUMENT",
+ "Idempotency-Key must be a valid Compile task ID.",
+ stage="queued",
+ ) from exc
+ if existing is not None:
+ if existing.principal_scope != principal_scope:
+ raise CompileFailure(
+ "PERMISSION_DENIED",
+ "Compile session belongs to another principal.",
+ stage="queued",
+ )
+ return CompileAccepted(
+ session_id=existing.task_id,
+ task_id=existing.task_id,
+ status="accepted",
+ to=existing.sanitized_request.to,
+ )
await self._admit(principal_scope)
runner_started = False
try:
@@ -398,7 +423,7 @@ class BotCompileService:
)
connection = connection or {}
normalized_request = await self._normalize_request(request, connection=connection)
- task_id = "cmp_" + uuid.uuid4().hex
+ task_id = task_id or "cmp_" + uuid.uuid4().hex
now = utc_now()
task = CompileTask(
task_id=task_id,
@@ -409,7 +434,22 @@ class BotCompileService:
created_at=now,
updated_at=now,
)
- await self.store.create(task)
+ try:
+ await self.store.create(task)
+ except FileExistsError:
+ existing = await self.store.get(task_id)
+ if existing is None or existing.principal_scope != principal_scope:
+ raise CompileFailure(
+ "PERMISSION_DENIED",
+ "Compile session belongs to another principal.",
+ stage="queued",
+ )
+ return CompileAccepted(
+ session_id=existing.task_id,
+ task_id=existing.task_id,
+ status="accepted",
+ to=existing.sanitized_request.to,
+ )
runner = asyncio.create_task(
self._run_admitted_task(
task_id,
@@ -422,7 +462,11 @@ class BotCompileService:
self._tasks.add(runner)
runner.add_done_callback(self._tasks.discard)
runner_started = True
- return CompileAccepted(task_id=task_id, to=normalized_request.to)
+ return CompileAccepted(
+ session_id=task_id,
+ task_id=task_id,
+ to=normalized_request.to,
+ )
finally:
if not runner_started:
await self._release_admission(principal_scope)
@@ -563,14 +607,10 @@ class BotCompileService:
*,
connection: Mapping[str, Any],
) -> SanitizedCompileRequest:
- if (
- request.runtime_timeout_seconds is not None
- and request.runtime_timeout_seconds > self.limits.task_runtime_seconds
- ):
+ if request.args:
raise CompileFailure(
- "RESOURCE_EXHAUSTED",
- "Compile runtime_timeout_seconds exceeds the server limit of "
- f"{self.limits.task_runtime_seconds:g} seconds.",
+ "INVALID_ARGUMENT",
+ "VikingBot Compile does not implement provider-specific args.",
stage="queued",
)
raw_sources = [str(value).strip() for value in request.from_]
@@ -649,7 +689,6 @@ class BotCompileService:
"reason": reason or DEFAULT_COMPILE_REASON,
"reason_provided": bool(reason),
"skill": canonical_skill,
- "runtime_timeout_seconds": request.runtime_timeout_seconds,
}
)
@@ -751,48 +790,11 @@ class BotCompileService:
task_lock = await self._retain_target_lock(request.to)
acquired = False
try:
- try:
- await asyncio.wait_for(
- self._acquire_execution_slot(task_lock),
- timeout=self.limits.queue_wait_seconds,
- )
- acquired = True
- except asyncio.TimeoutError:
- await self._fail(
- task_id,
- CompileFailure(
- "DEADLINE_EXCEEDED",
- "Compile task exceeded its queue wait limit.",
- stage="queued",
- ),
- )
- return
+ await self._acquire_execution_slot(task_lock)
+ acquired = True
try:
- runtime_timeout = min(
- request.runtime_timeout_seconds or self.limits.task_runtime_seconds,
- self.limits.task_runtime_seconds,
- )
- runtime_deadline = asyncio.get_running_loop().time() + runtime_timeout
- await asyncio.wait_for(
- self._execute_task(
- task_id,
- request,
- connection,
- runtime_deadline=runtime_deadline,
- ),
- timeout=runtime_timeout,
- )
- except asyncio.TimeoutError:
- task = await self.store.get(task_id)
- await self._fail(
- task_id,
- CompileFailure(
- "DEADLINE_EXCEEDED",
- "Compile task exceeded its runtime limit.",
- stage=task.stage if task else "agent",
- ),
- )
+ await self._execute_task(task_id, request, connection)
except CompileFailure as exc:
await self._fail(task_id, exc)
except Exception as exc:
@@ -812,8 +814,6 @@ class BotCompileService:
task_id: str,
request: SanitizedCompileRequest,
connection: dict[str, Any],
- *,
- runtime_deadline: float | None = None,
) -> None:
capabilities = self._compile_capabilities()
target_type = classify_uri(request.to).context_type
@@ -832,7 +832,6 @@ class BotCompileService:
sandbox: WorkspaceSandbox | None = None
workspace_baseline: set[str] | None = None
submit_tool: Any = None
- salvage_allowed = False
compile_started_at = time.monotonic()
agent_usage: dict[str, int] = {}
try:
@@ -1006,7 +1005,6 @@ class BotCompileService:
)
await self._set_state(task_id, status="running", stage="agent")
- salvage_allowed = True
try:
bundle, _tools, usage, _iterations = await request_loop.run_structured_task(
system_prompt=system_prompt,
@@ -1022,7 +1020,6 @@ class BotCompileService:
)
agent_usage = _merge_usage(agent_usage, usage or {})
except AgentIterationLimitExceeded as exc:
- salvage_allowed = False
agent_usage = _merge_usage(agent_usage, getattr(exc, "usage", None) or {})
if target_type != "resource":
raise CompileFailure("AGENT_OUTPUT_INVALID", str(exc), stage="agent") from exc
@@ -1038,10 +1035,8 @@ class BotCompileService:
)
return
except ValueError as exc:
- salvage_allowed = False
raise CompileFailure("AGENT_OUTPUT_INVALID", str(exc), stage="agent") from exc
- salvage_allowed = False
await self._set_state(task_id, status="running", stage="rendering")
file_payloads = list(getattr(submit_tool, "file_payloads", []))
if is_skill_target:
@@ -1053,7 +1048,7 @@ class BotCompileService:
bundle=bundle,
file_payloads=file_payloads,
skill_name=str(getattr(submit_tool, "skill_name", "") or ""),
- timeout=min(300.0, self.limits.task_runtime_seconds),
+ timeout=300.0,
)
except OpenVikingError as exc:
if exc.code == "CONFLICT":
@@ -1148,7 +1143,7 @@ class BotCompileService:
root_uri=request.to,
operations=rendered.operations,
wait=False,
- timeout=min(300.0, self.limits.task_runtime_seconds),
+ timeout=300.0,
)
except OpenVikingError as exc:
if exc.code == "CONFLICT":
@@ -1190,30 +1185,8 @@ class BotCompileService:
task.error = None
await self.store.update(task_id, complete)
- except asyncio.CancelledError:
- if (
- runtime_deadline is None
- or asyncio.get_running_loop().time() < runtime_deadline
- or client is None
- or target_type != "resource"
- or not salvage_allowed
- or getattr(submit_tool, "bundle", None) is not None
- ):
- raise
- task = await self.store.get(task_id)
- if task is None or task.status in TERMINAL_STATUSES or task.stage != "agent":
- raise
- assert sandbox is not None
- await self._complete_salvaged_task(
- task_id=task_id,
- client=client,
- request=request,
- sandbox=sandbox,
- workspace_baseline=workspace_baseline,
- reason="reached its runtime deadline",
- failure_code="DEADLINE_EXCEEDED",
- )
finally:
+ await self._record_usage(task_id, agent_usage)
self._log_compile_usage(
task_id,
elapsed_seconds=time.monotonic() - compile_started_at,
@@ -1347,7 +1320,7 @@ class BotCompileService:
request: SanitizedCompileRequest,
sandbox: WorkspaceSandbox,
workspace_baseline: set[str] | None,
- reason: str = "reached its runtime deadline",
+ reason: str = "reached its iteration limit",
) -> CompileResult | None:
baseline = workspace_baseline or set()
workspace_entries = sorted(
@@ -2553,6 +2526,24 @@ Selected Skill:
await self.store.update(task_id, mutate)
+ async def _record_usage(self, task_id: str, usage: Mapping[str, Any]) -> None:
+ input_tokens = int(usage.get("prompt_tokens", 0) or 0)
+ output_tokens = int(usage.get("completion_tokens", 0) or 0)
+ if input_tokens == 0 and output_tokens == 0:
+ return
+
+ def mutate(task: CompileTask) -> None:
+ task.meta["token_usage"] = {
+ "input_tokens": input_tokens,
+ "output_tokens": output_tokens,
+ "total_tokens": input_tokens + output_tokens,
+ }
+
+ try:
+ await self.store.update(task_id, mutate)
+ except (FileNotFoundError, ValueError):
+ return
+
async def _fail(self, task_id: str, failure: CompileFailure) -> None:
def mutate(task: CompileTask) -> None:
if task.status in TERMINAL_STATUSES or task.status == "cancelling":
diff --git a/crates/ov_cli/src/client.rs b/crates/ov_cli/src/client.rs
index 8c3106511..6b2a7dc68 100644
--- a/crates/ov_cli/src/client.rs
+++ b/crates/ov_cli/src/client.rs
@@ -115,45 +115,14 @@ pub enum SnapshotShowResult {
pub struct CompileAccepted {
pub task_id: String,
pub status: String,
- pub to: String,
-}
-
-#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
-pub struct CompileErrorInfo {
- pub code: String,
- pub message: String,
-}
-
-#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
-pub struct CompileResult {
- #[serde(rename = "from")]
- pub from_uris: Vec<String>,
- pub to: String,
- pub skill: String,
- pub okf_version: String,
#[serde(default)]
- pub created: Vec<String>,
+ pub to: Option<String>,
#[serde(default)]
- pub updated: Vec<String>,
+ pub task_type: Option<String>,
#[serde(default)]
- pub unchanged: Vec<String>,
- pub page_count: usize,
- pub link_count: usize,
+ pub stage: Option<String>,
#[serde(default)]
- pub warnings: Vec<String>,
-}
-
-#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
-pub struct CompileTaskStatus {
- pub task_id: String,
- pub status: String,
- pub stage: String,
- pub created_at: String,
- pub updated_at: String,
- #[serde(default)]
- pub result: Option<CompileResult>,
- #[serde(default)]
- pub error: Option<CompileErrorInfo>,
+ pub resource_id: Option<String>,
}
#[derive(serde::Serialize)]
@@ -165,7 +134,7 @@ struct CompileCreateRequest<'a> {
#[serde(skip_serializing_if = "Option::is_none")]
reason: Option<&'a str>,
#[serde(skip_serializing_if = "Option::is_none")]
- runtime_timeout_seconds: Option<f64>,
+ args: Option<&'a serde_json::Map<String, Value>>,
}
// ============ HttpClient ============
@@ -358,20 +327,16 @@ impl HttpClient {
to: &str,
skill: &str,
reason: Option<&str>,
- runtime_timeout_seconds: Option<f64>,
+ args: Option<&serde_json::Map<String, Value>>,
) -> Result<CompileAccepted> {
let body = CompileCreateRequest {
from_uris,
to,
skill,
reason,
- runtime_timeout_seconds,
+ args,
};
- self.post("/bot/v1/compile", &body).await
- }
-
- pub async fn get_compile(&self, task_id: &str) -> Result<CompileTaskStatus> {
- self.get(&format!("/bot/v1/compile/{task_id}"), &[]).await
+ self.post("/api/v1/compile", &body).await
}
pub async fn read(&self, uri: &str) -> Result<String> {
@@ -1331,20 +1296,12 @@ impl HttpClient {
// ============ Task Methods ============
pub async fn get_task(&self, task_id: &str) -> Result<serde_json::Value> {
- let path = if task_id.starts_with("cmp_") {
- format!("/bot/v1/compile/{task_id}")
- } else {
- format!("/api/v1/tasks/{task_id}")
- };
+ let path = format!("/api/v1/tasks/{task_id}");
self.get(&path, &[]).await
}
pub async fn cancel_task(&self, task_id: &str) -> Result<serde_json::Value> {
- let path = if task_id.starts_with("cmp_") {
- format!("/bot/v1/compile/{task_id}/cancel")
- } else {
- format!("/api/v1/tasks/{task_id}/cancel")
- };
+ let path = format!("/api/v1/tasks/{task_id}/cancel");
self.post(&path, &serde_json::json!({})).await
}
@@ -2669,7 +2626,8 @@ mod tests {
let mut buffer = vec![0; 4096];
let read = stream.read(&mut buffer).await.expect("request should read");
let request = String::from_utf8_lossy(&buffer[..read]);
- assert!(request.contains(r#""runtime_timeout_seconds":86400.0"#));
+ assert!(request.contains(r#""skill":"viking://agent/skills/wiki""#));
+ assert!(request.contains(r#""args":{"model_name":"endpoint-1"}"#));
let body = r#"{"status":"ok","result":{"task_id":"cmp_1","status":"accepted","to":"viking://resources/wiki"}}"#;
let response = format!(
"HTTP/1.1 202 Accepted\r\ncontent-type: application/json\r\ncontent-length: {}\r\nconnection: close\r\n\r\n{}",
@@ -2691,13 +2649,14 @@ mod tests {
false,
None,
);
+ let args = serde_json::json!({"model_name": "endpoint-1"});
let accepted = client
.create_compile(
&["viking://resources/source".into()],
"viking://resources/wiki",
"viking://agent/skills/wiki",
None,
- Some(86_400.0),
+ args.as_object(),
)
.await
.expect("202 response body should deserialize");
@@ -2705,7 +2664,7 @@ mod tests {
}
#[tokio::test]
- async fn task_methods_route_compile_ids_to_compile_endpoints() {
+ async fn task_methods_use_generic_task_endpoints_for_compile_ids() {
let (base_url, status_request_rx) = spawn_request_capture_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
client
@@ -2715,7 +2674,7 @@ mod tests {
let status_request = status_request_rx
.await
.expect("status request should be captured");
- assert!(status_request.starts_with("GET /bot/v1/compile/cmp_1 "));
+ assert!(status_request.starts_with("GET /api/v1/tasks/cmp_1 "));
let (base_url, cancel_request_rx) = spawn_request_capture_server().await;
let client = HttpClient::new(base_url, None, None, None, None, 5.0, false, None);
@@ -2726,7 +2685,7 @@ mod tests {
let cancel_request = cancel_request_rx
.await
.expect("cancel request should be captured");
- assert!(cancel_request.starts_with("POST /bot/v1/compile/cmp_1/cancel "));
+ assert!(cancel_request.starts_with("POST /api/v1/tasks/cmp_1/cancel "));
}
#[tokio::test]
diff --git a/crates/ov_cli/src/commands/compile.rs b/crates/ov_cli/src/commands/compile.rs
index 122e66a3b..11be6202d 100644
--- a/crates/ov_cli/src/commands/compile.rs
+++ b/crates/ov_cli/src/commands/compile.rs
@@ -1,10 +1,7 @@
-use std::time::Duration;
-
-use tokio::time::Instant;
-
-use crate::client::{CompileAccepted, CompileResult, CompileTaskStatus, HttpClient};
+use crate::client::{CompileAccepted, HttpClient};
use crate::error::{Error, Result};
use crate::output::{OutputFormat, output_success};
+use serde_json::{Map, Value};
pub async fn run(
client: &HttpClient,
@@ -12,74 +9,33 @@ pub async fn run(
to: String,
skill: String,
reason: Option<String>,
- wait: bool,
- timeout: Option<f64>,
- runtime_timeout: Option<f64>,
+ args: Option<String>,
output_format: OutputFormat,
compact: bool,
) -> Result<()> {
let sources = normalize_sources(from_uris)?;
- if timeout.is_some_and(|seconds| !crate::config::timeout_is_valid(seconds)) {
- return Err(Error::Client(
- "--timeout must be a positive finite number of seconds".into(),
- ));
- }
+ let args = parse_args(args.as_deref())?;
let reason = reason
.as_deref()
.map(str::trim)
.filter(|value| !value.is_empty());
let accepted = client
- .create_compile(&sources, to.trim(), skill.trim(), reason, runtime_timeout)
+ .create_compile(&sources, to.trim(), skill.trim(), reason, args.as_ref())
.await?;
- if !wait {
- render_accepted(&accepted, output_format, compact);
- return Ok(());
- }
-
- let deadline = timeout.map(|seconds| Instant::now() + Duration::from_secs_f64(seconds));
- let mut polling = Duration::from_millis(500);
- loop {
- if deadline.is_some_and(|value| Instant::now() >= value) {
- return Err(Error::Client(format!(
- "Timed out waiting for compile task {}; the task is still running",
- accepted.task_id
- )));
- }
- let status = client.get_compile(&accepted.task_id).await?;
- match status.status.as_str() {
- "completed" => {
- render_completed(&status, output_format, compact);
- return Ok(());
- }
- "failed" => {
- let error = status.error.unwrap_or(crate::client::CompileErrorInfo {
- code: "UNKNOWN".into(),
- message: "Compile task failed".into(),
- });
- return Err(Error::api_response(
- Some(error.code),
- error.message,
- None,
- 500,
- ));
- }
- "cancelled" => {
- return Err(Error::api_response(
- Some("CANCELLED".into()),
- format!("Compile task {} was cancelled", accepted.task_id),
- None,
- 409,
- ));
- }
- _ => {}
- }
+ render_accepted(&accepted, to.trim(), output_format, compact);
+ Ok(())
+}
- let sleep_for = deadline
- .map(|value| polling.min(value.saturating_duration_since(Instant::now())))
- .unwrap_or(polling);
- tokio::time::sleep(sleep_for).await;
- polling = (polling * 2).min(Duration::from_secs(2));
- }
+fn parse_args(value: Option<&str>) -> Result<Option<Map<String, Value>>> {
+ let Some(value) = value else {
+ return Ok(None);
+ };
+ let parsed: Value = serde_json::from_str(value)
+ .map_err(|err| Error::Client(format!("--args must be valid JSON: {err}")))?;
+ let Value::Object(args) = parsed else {
+ return Err(Error::Client("--args must be a JSON object".into()));
+ };
+ Ok((!args.is_empty()).then_some(args))
}
fn normalize_sources(values: Vec<String>) -> Result<Vec<String>> {
@@ -103,51 +59,24 @@ fn normalize_sources(values: Vec<String>) -> Result<Vec<String>> {
Ok(result)
}
-fn render_accepted(value: &CompileAccepted, format: OutputFormat, compact: bool) {
+fn render_accepted(
+ value: &CompileAccepted,
+ requested_to: &str,
+ format: OutputFormat,
+ compact: bool,
+) {
if matches!(format, OutputFormat::Json) {
output_success(value, format, compact);
} else {
println!("task_id: {}", value.task_id);
println!("status: {}", value.status);
- println!("to: {}", value.to);
- }
-}
-
-fn render_completed(value: &CompileTaskStatus, format: OutputFormat, compact: bool) {
- if matches!(format, OutputFormat::Json) {
- output_success(value, format, compact);
- return;
- }
- let result = value
- .result
- .as_ref()
- .cloned()
- .unwrap_or_else(|| CompileResult {
- from_uris: Vec::new(),
- to: String::new(),
- skill: String::new(),
- okf_version: "0.1".into(),
- created: Vec::new(),
- updated: Vec::new(),
- unchanged: Vec::new(),
- page_count: 0,
- link_count: 0,
- warnings: Vec::new(),
- });
- println!("to: {}", result.to);
- println!("created: {}", result.created.len());
- println!("updated: {}", result.updated.len());
- println!("unchanged: {}", result.unchanged.len());
- println!("page_count: {}", result.page_count);
- println!("link_count: {}", result.link_count);
- for warning in result.warnings {
- eprintln!("warning: {warning}");
+ println!("to: {}", value.to.as_deref().unwrap_or(requested_to));
}
}
#[cfg(test)]
mod tests {
- use super::normalize_sources;
+ use super::{normalize_sources, parse_args};
#[test]
fn expands_comma_separated_and_repeated_sources_stably() {
@@ -162,5 +91,10 @@ mod tests {
#[test]
fn rejects_empty_source_items() {
assert!(normalize_sources(vec!["viking://resources/a,".into()]).is_err());
+ let args = parse_args(Some(r#"{"model_name":"endpoint-1"}"#))
+ .expect("args should be valid")
+ .expect("args should not be empty");
+ assert_eq!(args["model_name"], "endpoint-1");
+ assert!(parse_args(Some("[]")).is_err());
}
}
diff --git a/crates/ov_cli/src/error_ui.rs b/crates/ov_cli/src/error_ui.rs
index 05e3285d7..c94397d8f 100644
--- a/crates/ov_cli/src/error_ui.rs
+++ b/crates/ov_cli/src/error_ui.rs
@@ -1124,7 +1124,7 @@ Usage: ov config [OPTIONS] [COMMAND]
#[test]
fn compile_refresh_failure_explains_safe_retry() {
- let command = "ov compile --from viking://resources/source --to viking://resources/wiki --skill viking://agent/skills/wiki --wait";
+ let command = "ov compile --from viking://resources/source --to viking://resources/wiki --skill viking://agent/skills/wiki";
let error = Error::api_response(
Some("REFRESH_FAILED".to_string()),
"Content is already at the requested state, but semantic/index refresh failed: injected overview failure. Re-run the same batch-write or ov compile command; matching files will remain unchanged and refresh will be retried.",
diff --git a/crates/ov_cli/src/help_ui.rs b/crates/ov_cli/src/help_ui.rs
index 985d9da8e..aa006c35d 100644
--- a/crates/ov_cli/src/help_ui.rs
+++ b/crates/ov_cli/src/help_ui.rs
@@ -867,11 +867,11 @@ const COMMAND_HELP_SPECS: &[CommandHelpSpec] = &[
purpose: "Use a required VikingBot Skill to compile OpenViking materials into Wiki pages or a Skill package.",
examples: &[
HelpItem {
- label: "ov compile --from viking://resources/weekly --to viking://resources/wiki --skill viking://agent/skills/monthly_wiki --wait",
+ label: "ov compile --from viking://resources/weekly --to viking://resources/wiki --skill viking://agent/skills/monthly_wiki",
description: "Compile one source directory into Wiki pages.",
},
HelpItem {
- label: "ov compile --from viking://resources/weekly --to viking://agent/skills --skill viking://agent/skills/skill-creator --wait",
+ label: "ov compile --from viking://resources/weekly --to viking://agent/skills --skill viking://agent/skills/skill-creator",
description: "Generate or update one shared Skill package.",
},
],
diff --git a/crates/ov_cli/src/main.rs b/crates/ov_cli/src/main.rs
index 2f2aec367..d88732e1d 100644
--- a/crates/ov_cli/src/main.rs
+++ b/crates/ov_cli/src/main.rs
@@ -1167,24 +1167,9 @@ enum Commands {
/// Description of this organization task
#[arg(long, value_name = "text")]
reason: Option<String>,
- /// Wait for the Compile task to finish
- #[arg(long)]
- wait: bool,
- /// Local wait timeout in seconds; does not cancel the task
- #[arg(
- long,
- requires = "wait",
- value_parser = config::parse_positive_timeout,
- value_name = "seconds"
- )]
- timeout: Option<f64>,
- /// Server-side runtime limit in seconds; reaching it saves partial resource output
- #[arg(
- long = "runtime-timeout",
- value_parser = config::parse_positive_timeout,
- value_name = "seconds"
- )]
- runtime_timeout: Option<f64>,
+ /// Provider arguments as a JSON object
+ #[arg(long, value_name = "json")]
+ args: Option<String>,
},
// --- Status & Observability ---
@@ -3676,9 +3661,7 @@ async fn main() {
to,
skill,
reason,
- wait,
- timeout,
- runtime_timeout,
+ args,
} => {
let client = ctx.get_client();
commands::compile::run(
@@ -3687,9 +3670,7 @@ async fn main() {
to,
skill,
reason,
- wait,
- timeout,
- runtime_timeout,
+ args,
ctx.output_format,
ctx.compact,
)
@@ -4131,11 +4112,8 @@ mod tests {
"viking://resources/wiki",
"--skill",
"viking://agent/skills/wiki",
- "--wait",
- "--timeout",
- "10",
- "--runtime-timeout",
- "86400",
+ "--args",
+ r#"{"model_name":"endpoint-1"}"#,
])
.expect("compile flags should parse");
match cli.command {
@@ -4143,17 +4121,13 @@ mod tests {
from_uris,
skill,
reason,
- wait,
- timeout,
- runtime_timeout,
+ args,
..
} => {
assert_eq!(from_uris.len(), 3);
assert_eq!(skill, "viking://agent/skills/wiki");
assert!(reason.is_none());
- assert!(wait);
- assert_eq!(timeout, Some(10.0));
- assert_eq!(runtime_timeout, Some(86_400.0));
+ assert_eq!(args.as_deref(), Some(r#"{"model_name":"endpoint-1"}"#));
}
_ => panic!("expected compile command"),
}
@@ -4169,21 +4143,6 @@ mod tests {
])
.is_err()
);
- assert!(
- Cli::try_parse_from([
- "ov",
- "compile",
- "--from",
- "viking://resources/a",
- "--to",
- "viking://resources/wiki",
- "--skill",
- "viking://agent/skills/wiki",
- "--timeout",
- "10",
- ])
- .is_err()
- );
}
#[test]
@@ -5061,18 +5020,6 @@ mod tests {
"value",
"--timeout",
],
- vec![
- "ov",
- "compile",
- "--from",
- "viking://resources/source",
- "--to",
- "viking://resources/target",
- "--skill",
- "viking://user/skills/compiler",
- "--wait",
- "--timeout",
- ],
vec!["ov", "wait", "--timeout"],
vec!["ov", "system", "wait", "--timeout"],
];
diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
index 2722af98d..416e9a86b 100644
--- a/docs/.vitepress/config.ts
+++ b/docs/.vitepress/config.ts
@@ -246,6 +246,7 @@ const apiReferenceSidebar = {
items: [
['22-openviking-assets.md', 'OpenViking Assets'],
['20-webdav.md', 'WebDAV'],
+ ['23-agent-runtime.md', 'Agent Runtime API'],
['24-vikingbot.md', 'VikingBot API']
]
},
@@ -303,6 +304,7 @@ const apiReferenceSidebar = {
items: [
['22-openviking-assets.md', 'OpenViking Assets'],
['20-webdav.md', 'WebDAV'],
+ ['23-agent-runtime.md', 'Agent Runtime API'],
['24-vikingbot.md', 'VikingBot API']
]
},
diff --git a/docs/design/ov-compile-design.md b/docs/design/ov-compile-design.md
index 777aa9f4b..761f4cb94 100644
--- a/docs/design/ov-compile-design.md
+++ b/docs/design/ov-compile-design.md
@@ -2,9 +2,11 @@
| 项目 | 信息 |
| --- | --- |
-| 状态 | 待实现 |
+| 状态 | 历史设计,现行方案见下方说明 |
| 目标版本 | v1 |
-| 更新日期 | 2026-07-20 |
+| 更新日期 | 2026-08-28 |
+
+> 本文保留最初由 VikingBot 直接托管任务的历史设计。现行方案由 OpenViking 托管 TaskRecord、QueueFS、查询和取消,外部 Server 只负责执行。
## 1. 概述
@@ -37,7 +39,7 @@ ov compile \
--to viking://resources/团队知识库 \
--reason "按月整理团队的成本优化进展" \
--skill viking://agent/skills/monthly_wiki \
- --wait
+ --args '{"model_name":"your-model-endpoint-id"}'
```
| 参数 | 规则 |
@@ -46,16 +48,13 @@ ov compile \
| `--to` | 必填,目标 Wiki 目录 |
| `--skill` | 必填,Skill 目录或 `SKILL.md` 的 Viking URI |
| `--reason` | 可选,本次整理任务的描述 |
-| `--wait` | 可选,等待任务完成 |
-| `--timeout` | 可选,仅与 `--wait` 一起使用;只限制 CLI 等待时间,不取消任务 |
-| `--runtime-timeout` | 可选,正数且有限的服务端运行时限;只能缩短服务端最大值(默认 60 分钟) |
+| `--args` | 可选,Provider 扩展参数 JSON 对象;`model_name` 可传模型 Endpoint ID |
参数在 OpenViking 用户身份下 canonicalize 后满足以下约束:
- `from` 必须是一个或多个可读目录;重复项去重,空项报错;
- `to` 必须是可写的 resource 或 memory 目录,不能是 namespace 根、文件、Skill 目录或 OpenViking 派生目录;
- `skill` 必须解析为 Skill root,目录 URI 和其 `SKILL.md` URI 视为同一个 Skill;
-- `runtime_timeout_seconds` 省略时使用服务端最大值,显式值不得超过该上限;
- `from`、`to` 和 `skill` 的权限最终仍由 OpenViking Server 校验,CLI 不根据 URI 文本推断权限。
`--reason` 为空时,VikingBot 使用以下默认任务描述:
@@ -66,7 +65,7 @@ Follow the loaded Skill's instructions to transform the provided source material
### 2.2 返回结果
-未指定 `--wait` 时,CLI 在任务创建后返回:
+CLI 在任务创建后立即返回:
```text
task_id: cmp_01...
@@ -74,22 +73,9 @@ status: accepted
to: viking://resources/团队知识库
```
-指定 `--wait` 时,CLI 轮询任务并返回最终结果:
-
-```text
-to: viking://resources/团队知识库
-created: 1
-updated: 2
-unchanged: 3
-page_count: 6
-link_count: 8
-```
+CLI 不等待任务完成。用户通过 `ov task status <task_id>` 查询状态和结果,通过 `ov task cancel <task_id>` 取消任务。
-完整 URI 列表通过全局 JSON 输出返回。
-
-`created`、`updated` 和 `unchanged` 只统计 Agent 本次提交的页面;未被草稿触达的目标页面不计入 `unchanged`。`page_count` 等于三者之和,`link_count` 只统计最终正文中实际渲染出的 bundle 内 WikiLink。
-
-`--wait` 使用单调时钟计算整体等待 deadline,并以有上限的 polling interval 查询任务;CLI timeout 或 Ctrl-C 只结束本地等待,不向 Bot 发送取消请求。
+Task 结果中的 `created`、`updated` 和 `unchanged` 只统计 Agent 本次提交的页面;未被草稿触达的目标页面不计入 `unchanged`。`page_count` 等于三者之和,`link_count` 只统计最终正文中实际渲染出的 bundle 内 WikiLink。
## 3. 架构
@@ -188,8 +174,6 @@ VikingBot 负责规范化参数并计算实际任务描述:
effective_reason = (request.reason or "").strip() or DEFAULT_COMPILE_REASON
```
-可选的 `runtime_timeout_seconds` 必须为正数且有限,并且只能缩短 `CompileLimits.task_runtime_seconds` 定义的服务端最大值(默认 3600 秒);超限请求在创建任务时以 `RESOURCE_EXHAUSTED` 拒绝。
-
### 4.2 查询任务
```http
@@ -562,11 +546,11 @@ task_id, principal_scope, sanitized_request, status, stage, timestamps, result,
Bot 当前没有通用的持久化后台任务管理器,因此这里实现一个最小 JSON task store,使用 per-task lock 和临时文件原子替换。进程内以有界的 `asyncio.Task` 集合和 semaphore 承载 accepted task;全局和单 principal admission 在任务创建前计数,超限同步返回 `RESOURCE_EXHAUSTED`。现有 `SessionManager` 继续只管理 chat JSONL,不承载 Compile 状态。
-`sanitized_request` 只包含 canonical `from/to/skill`、effective reason 和可选的 `runtime_timeout_seconds`;`openviking_connection` 仅由运行中 `asyncio.Task` 持有,不进入 JSON、异常详情或日志。
+`sanitized_request` 只包含 canonical `from/to/skill` 和 effective reason;`openviking_connection` 仅由运行中 `asyncio.Task` 持有,不进入 JSON、异常详情或日志。
运行中任务目录可以保存有大小限制的 Skill 快照、catalog 和 draft,但不能保存用户凭证。任务进入终态后删除 workspace、Skill snapshot 和 draft;task/result/error JSON 最长保留 24 小时且最多保留 1,000 条,启动和任务结束时都会清理。
-VikingBot 使用独立的 compile 并发限制,并对同一 canonical 目标目录串行执行。accepted task 最多排队 60 分钟,取得 target lock 和全局执行 slot 后才开始计算 runtime;服务端最大值和缺省值均为 60 分钟,客户端只能请求更短的时限,超限请求以 `RESOURCE_EXHAUSTED` 拒绝。只有 Agent 阶段的 runtime deadline 和迭代上限允许 salvage;salvage 与 cleanup 各自受独立的短 grace deadline 约束,rendering/writing/refreshing 阶段超时直接失败。该锁只减少同一 Bot 进程内的浪费;跨进程或人工写入冲突仍由 batch-write 的 tree lock 和 content hash 检查解决。v1 task store 以单个 VikingBot gateway 进程为部署边界,不承诺多副本共享 task 查询。
+VikingBot 使用独立的 compile 并发限制,并对同一 canonical 目标目录串行执行。accepted task 最多排队 60 分钟,取得 target lock 和全局执行 slot 后持续运行,直到任务完成、失败或被取消。Agent 阶段达到迭代上限时允许 salvage;salvage 与 cleanup 各自受独立的短 grace deadline 约束。该锁只减少同一 Bot 进程内的浪费;跨进程或人工写入冲突仍由 batch-write 的 tree lock 和 content hash 检查解决。v1 task store 以单个 VikingBot gateway 进程为部署边界,不承诺多副本共享 task 查询。
VikingBot 启动时把 store 中所有非终态任务统一标记为 `BOT_RESTARTED`,包括处于 committing 的任务;因为 API key 不落盘,重启后不能安全恢复原任务。用户可以重新提交,batch-write 通过最终 content hash 跳过已落盘内容并继续收敛。
@@ -655,7 +639,7 @@ bot/vikingbot/compile/
至少覆盖:
-- CLI 参数展开、默认 reason、`--wait` 和 timeout;
+- CLI 参数展开、默认 reason 和 Task ID 返回;
- Bot proxy 的创建/GET 查询身份转交、未启用 Bot 的 503 和上游错误;
- Skill 复用现有 parser/loader、相对引用、requirements 和路径逃逸检查;`allowed-tools` 可正常解析但不影响 Compile 工具集合;
- request registry 固定包含本地核心工具、scope-guarded OpenViking 只读工具和 `submit_wiki_bundle`,不包含 message/cron/spawn/Web/image/MCP/OV write,用户 connection 只进入 OV read adapter;
@@ -675,8 +659,7 @@ ov compile \
--from viking://resources/周报 \
--to viking://resources/团队知识库 \
--reason "按月整理团队的成本优化进展" \
- --skill viking://agent/skills/monthly_wiki \
- --wait
+ --skill viking://agent/skills/monthly_wiki
```
验收结果:
diff --git a/docs/en/api/01-overview.md b/docs/en/api/01-overview.md
index 8f398f5d0..d9666cc87 100644
--- a/docs/en/api/01-overview.md
+++ b/docs/en/api/01-overview.md
@@ -465,6 +465,7 @@ This catalog follows the routes actually mounted by the server. Each group headi
| Method | Path | Description |
|--------|------|-------------|
+| POST | `/api/v1/compile` | Create an OV-owned Compile task |
| GET | `/api/v1/tasks/{task_id}` | Get a background task |
| POST | `/api/v1/tasks/{task_id}/cancel` | Cancel a background task |
| GET | `/api/v1/tasks` | List background tasks |
@@ -510,7 +511,7 @@ This catalog follows the routes actually mounted by the server. Each group headi
| POST | `/api/v1/privacy-configs/{category}/{target_key}` | Write and activate a new version |
| POST | `/api/v1/privacy-configs/{category}/{target_key}/activate` | Activate a version |
-### [OpenViking Assets](22-openviking-assets.md), [WebDAV](20-webdav.md), and [VikingBot API](24-vikingbot.md)
+### [OpenViking Assets](22-openviking-assets.md), [WebDAV](20-webdav.md), [Agent Runtime API](23-agent-runtime.md), and [VikingBot API](24-vikingbot.md)
| Method | Path | Description |
|--------|------|-------------|
@@ -523,13 +524,14 @@ This catalog follows the routes actually mounted by the server. Each group headi
| DELETE | `/webdav/resources`, `/webdav/resources/{resource_path}` | Delete a file or directory |
| MKCOL | `/webdav/resources`, `/webdav/resources/{resource_path}` | Create a directory |
| MOVE | `/webdav/resources`, `/webdav/resources/{resource_path}` | Move or rename a resource |
+| POST | `/api/v1/compile` | Create an asynchronous Compile task |
| GET | `/bot/v1/health` | VikingBot health check |
| POST | `/bot/v1/chat` | Non-streaming VikingBot chat |
| POST | `/bot/v1/chat/stream` | Streaming VikingBot chat |
| POST | `/bot/v1/feedback` | Submit feedback for a VikingBot answer |
-| POST | `/bot/v1/compile` | Start a Skill-driven Compile task |
-| GET | `/bot/v1/compile/{task_id}` | Get Compile task status |
-| POST | `/bot/v1/compile/{task_id}/cancel` | Cancel a Compile task |
+| POST | `/bot/v1/compile` | Retired; returns migration guidance for the new endpoint |
+| GET | `/bot/v1/compile/{task_id}` | Retired; returns Task API migration guidance |
+| POST | `/bot/v1/compile/{task_id}/cancel` | Retired; returns Task cancellation API migration guidance |
---
@@ -544,4 +546,4 @@ The sidebar is organized by responsibility rather than historical file size:
| Data Lifecycle | Watches, snapshots, and OVPack |
| Operations & Observability | System, tasks, Observer, and Metrics |
| Identity & Governance | Administration, ACL, and privacy configuration |
-| Protocols & Extensions | OpenViking Assets, WebDAV, and VikingBot API |
+| Protocols & Extensions | OpenViking Assets, WebDAV, Agent Runtime API, and VikingBot API |
diff --git a/docs/en/api/23-agent-runtime.md b/docs/en/api/23-agent-runtime.md
new file mode 100644
index 000000000..1577b1abd
--- /dev/null
+++ b/docs/en/api/23-agent-runtime.md
@@ -0,0 +1,224 @@
+# Agent Runtime API
+
+Agent Runtime Server executes Agent tasks and currently supports Compile. Applications submit tasks through OpenViking's Compile API. OpenViking validates requests, persists tasks, and manages their lifecycle while calling the Runtime execution API. The bundled VikingBot implements the same execution protocol for local deployments.
+
+**Code entry points**:
+
+- `openviking/server/routers/compile.py` - Compile task creation
+- `openviking/server/routers/tasks.py` - task inspection and cancellation
+- `openviking/service/compile_service.py` - Runtime calls and task state convergence
+
+## Compile task API
+
+### Create a task
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `from` | string[] | Yes | - | One or more source directories |
+| `to` | string | Yes | - | Target Resource or Memory directory, or a supported Skill namespace |
+| `skill` | string | Yes | - | Skill directory or its `SKILL.md` URI |
+| `reason` | string | No | Skill-driven default | Additional instructions for this Compile run |
+| `args` | object | No | - | Execution backend extensions; `model_name` accepts a model endpoint ID |
+
+The entire `args` object is optional, and the model endpoint ID is not a top-level field. Use `args.model_name` to select a model; when omitted, the execution backend uses its default model configuration.
+
+**HTTP API**
+
+```http
+POST /api/v1/compile
+```
+
+```bash
+curl -X POST http://localhost:1933/api/v1/compile \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{
+ "from": ["viking://resources/research"],
+ "to": "viking://resources/research-wiki",
+ "skill": "viking://user/default/skills/research-compiler",
+ "reason": "Track the historical progress and preserve supporting evidence.",
+ "args": {"model_name": "your-model-endpoint-id"}
+ }'
+```
+
+The endpoint returns `202 Accepted` with an OV task record:
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "task_id": "cmp_01abc",
+ "task_type": "compile",
+ "status": "pending",
+ "stage": "queued",
+ "resource_id": "viking://resources/research"
+ }
+}
+```
+
+**CLI**
+
+```bash
+ov compile \
+ --from viking://resources/research \
+ --to viking://resources/research-wiki \
+ --skill viking://user/default/skills/research-compiler \
+ --reason "Track the historical progress and preserve supporting evidence." \
+ --args '{"model_name":"your-model-endpoint-id"}'
+```
+
+`--args` must be a JSON object. The command returns a task ID immediately after submission.
+
+**SDKs**
+
+The Python, TypeScript, and Go SDKs pass `reason` and `args` through their Compile options:
+
+::: code-group
+
+```python [Python]
+task = client.compile(
+ ["viking://resources/research"],
+ "viking://resources/research-wiki",
+ "viking://user/default/skills/research-compiler",
+ {"args": {"model_name": "your-model-endpoint-id"}},
+)
+```
+
+```ts [TypeScript]
+const task = await client.compile(
+ ["viking://resources/research"],
+ "viking://resources/research-wiki",
+ "viking://user/default/skills/research-compiler",
+ { args: { model_name: "your-model-endpoint-id" } },
+);
+```
+
+```go [Go]
+task, err := client.Compile(
+ ctx,
+ []string{"viking://resources/research"},
+ "viking://resources/research-wiki",
+ "viking://user/default/skills/research-compiler",
+ &openviking.CompileOptions{
+ Args: map[string]any{"model_name": "your-model-endpoint-id"},
+ },
+)
+```
+
+:::
+
+### Get task status
+
+A task is visible only to the principal that created it. A missing task and a task owned by another principal both return `404`.
+
+```http
+GET /api/v1/tasks/{task_id}
+```
+
+```bash
+ov task status cmp_01abc
+```
+
+Terminal task responses also contain the result or error.
+
+### Cancel a task
+
+```http
+POST /api/v1/tasks/{task_id}/cancel
+```
+
+```bash
+ov task cancel cmp_01abc
+```
+
+The task first enters `cancelling`, then becomes `cancelled` after in-process work and cleanup settle. Writes that already completed are not rolled back. Repeated cancellation of an already `cancelled` task is idempotent.
+
+| Status | Typical stages |
+|--------|----------------|
+| `pending` | `queued` |
+| `running` | Execution stage reported by the backend, such as `agent` or `writing` |
+| `cancelling` | Settling in-process work and resource cleanup |
+| `completed` | `completed`, `salvaged` |
+| `failed` | Stage where the failure occurred; the response contains `error` |
+| `cancelled` | `cancelled` |
+
+### Legacy endpoints
+
+The following legacy VikingBot proxy routes on OV are retired and return migration guidance only:
+
+```http
+POST /bot/v1/compile
+GET /bot/v1/compile/{task_id}
+POST /bot/v1/compile/{task_id}/cancel
+```
+
+Create tasks through `/api/v1/compile`; inspect and cancel them through `/api/v1/tasks/{task_id}`.
+
+## Runtime execution API
+
+The execution service configured by `compile_api.base_url` provides the following endpoints for OV. Applications submit tasks through the Compile API above.
+
+### Create an execution task
+
+```http
+POST /runtime/v1/tasks
+Idempotency-Key: <OV task_id>
+```
+
+```json
+{
+ "task_type": "compile",
+ "payload": {
+ "from": ["viking://resources/research"],
+ "to": "viking://resources/research-wiki",
+ "skill": "viking://agent/skills/wiki",
+ "reason": "Organize the sources into a knowledge base.",
+ "args": {"model_name": "your-model-endpoint-id"}
+ }
+}
+```
+
+Both `task_type` and `payload` are required. Only `task_type="compile"` is supported. The `payload` uses the task creation fields and validation rules described on this page; `reason` and `args` are optional. Bundled VikingBot does not support non-empty `args`. Unsupported types or invalid payloads return `4xx` without creating an execution task.
+
+OV forwards the current user's OV API key in `X-API-Key`. It also sends `X-Gateway-Token` when `compile_api.gateway_token` is configured. These credentials must not appear in public task results.
+
+An accepted request returns `202 Accepted` with an execution identifier:
+
+```json
+{"session_id": "session-123"}
+```
+
+Repeated requests with the same `Idempotency-Key` from the same user must return the same `session_id` without executing again. Use `session_id` to inspect or cancel execution on the backend; applications use `task_id` to inspect their OV task.
+
+### Inspect or cancel an execution task
+
+```http
+POST /runtime/v1/tasks/status
+POST /runtime/v1/tasks/cancel
+```
+
+Both endpoints accept this request body:
+
+```json
+{"session_id": "session-123"}
+```
+
+Both return an execution status, for example:
+
+```json
+{
+ "status": "running",
+ "stage": "compile: agent",
+ "error": null,
+ "meta": {},
+ "result": null
+}
+```
+
+The `status` is one of `pending`, `running`, `cancelling`, `completed`, `failed`, or `cancelled`. Cancellation may return `cancelling` until execution has stopped and cleanup has finished, then return `cancelled`. Repeated cancellation of a terminal task returns its current terminal state. Both inspection and cancellation must enforce task ownership.
+
+## Related documentation
+
+- [Background Tasks](17-tasks.md) - generic task inspection, cancellation, and listing
+- [Context Compilation](../context-compilation/01-overview.md) - Compile scenarios and examples
+- [Skills API](04-skills.md) - managing the Skills used by Compile
diff --git a/docs/en/api/24-vikingbot.md b/docs/en/api/24-vikingbot.md
index 90e631242..d43c75392 100644
--- a/docs/en/api/24-vikingbot.md
+++ b/docs/en/api/24-vikingbot.md
@@ -135,147 +135,6 @@ data: {"event":"response","data":{"content":"The knowledge base contains…","re
`event` can be `reasoning`, `reasoning_delta`, `tool_call`, `tool_result`, `content_delta`, `iteration`, or `response`.
-### compile()
-
-Start an asynchronous, Skill-driven Compile task. VikingBot loads the selected Skill, reads the supplied OpenViking directories with the authenticated user identity, runs a task-scoped AgentLoop, and commits validated outputs below the target URI.
-
-| Field | Type | Required | Default | Description |
-|-------|------|----------|---------|-------------|
-| `from` | string[] | Yes | - | One or more source directories |
-| `to` | string | Yes | - | Target Resource or Memory directory, or a supported Skill namespace |
-| `skill` | string | Yes | - | Skill directory or its `SKILL.md` URI |
-| `reason` | string | No | Skill-driven default | Additional instructions for this Compile run |
-| `runtime_timeout_seconds` | number | No | 3600 | Positive finite runtime limit no greater than the server maximum (3600 seconds by default) |
-
-**HTTP API**
-
-```
-POST /bot/v1/compile
-```
-
-```bash
-curl -X POST http://localhost:1933/bot/v1/compile \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
- -d '{
- "from": ["viking://resources/research"],
- "to": "viking://resources/research-wiki",
- "skill": "viking://user/default/skills/research-compiler",
- "reason": "Track the historical progress and preserve supporting evidence."
- }'
-```
-
-**CLI**
-
-```bash
-ov compile \
- --from viking://resources/research \
- --to viking://resources/research-wiki \
- --skill viking://user/default/skills/research-compiler \
- --reason "Track the historical progress and preserve supporting evidence." \
- --wait
-```
-
-`--wait` polls the status endpoint until the task reaches a terminal state. `--timeout` limits only the local wait and does not cancel the server task. `--runtime-timeout` sets `runtime_timeout_seconds` for this run and can only shorten the server-owned runtime maximum; an excessive value is rejected with `429 RESOURCE_EXHAUSTED`. Reaching that deadline while the Agent is running, or reaching the configured AgentLoop iteration limit (`bot.agents.max_tool_iterations`, 50 by default), attempts to save eligible partial Resource output within a separate short grace period. The task fails if there is no eligible output to save; non-Resource targets and deadlines in later stages do not use this fallback.
-
-The `direct` backend runs Compile `exec` commands with the Bot host's permissions. `bot.sandbox.backends.direct.allow_compile_exec` defaults to `true`: the Compile toolchain is open source, so `exec` runs directly in the user's shell by default, and ordinary Wiki and artifact generation run through file tools as before. A Skill that declares `requires.bins` or `requires.env` still probes the commands; set the option to `false` to omit `exec` from Compile (then such Skills fail with `SKILL_CAPABILITY_UNAVAILABLE` before any command probe runs). Isolated backends with filesystem and network policies are recommended for CLI-dependent Skills. Admission overflow returns `429 RESOURCE_EXHAUSTED`.
-
-**Response Example**
-
-The HTTP endpoint returns `202 Accepted`:
-
-```json
-{
- "status": "ok",
- "result": {
- "task_id": "cmp_01abc",
- "status": "accepted",
- "to": "viking://resources/research-wiki"
- }
-}
-```
-
-### compile_status()
-
-Get the current state and, for a terminal task, its result or error. A task is visible only to the principal that created it; a missing task and a task owned by another principal both return `404`.
-
-**HTTP API**
-
-```
-GET /bot/v1/compile/{task_id}
-```
-
-```bash
-curl http://localhost:1933/bot/v1/compile/cmp_01abc \
- -H "X-API-Key: your-key"
-```
-
-The CLI accepts the `cmp_...` task ID returned by Compile directly:
-
-```bash
-ov task status cmp_01abc
-```
-
-**Response Example**
-
-```json
-{
- "status": "ok",
- "result": {
- "task_id": "cmp_01abc",
- "status": "completed",
- "stage": "completed",
- "created_at": "2026-07-28T08:00:00Z",
- "updated_at": "2026-07-28T08:02:30Z",
- "result": {
- "from": ["viking://resources/research"],
- "to": "viking://resources/research-wiki",
- "skill": "viking://user/default/skills/research-compiler",
- "okf_version": "0.1",
- "created": ["viking://resources/research-wiki/Progress.md"],
- "updated": [],
- "unchanged": [],
- "page_count": 1,
- "link_count": 0,
- "warnings": []
- }
- }
-}
-```
-
-### compile_cancel()
-
-Request cooperative cancellation of a Compile task by task ID. The task first enters `cancelling`, then becomes `cancelled` after its in-process work and cleanup settle. Writes that already completed are not rolled back. Repeated cancellation of a `cancelled` task is idempotent; a missing task or a task owned by another principal returns `404`.
-
-**CLI**
-
-```bash
-ov task cancel cmp_01abc
-```
-
-**HTTP API**
-
-```http
-POST /bot/v1/compile/{task_id}/cancel
-```
-
-```bash
-curl -X POST http://localhost:1933/bot/v1/compile/cmp_01abc/cancel \
- -H "X-API-Key: your-key"
-```
-
-Task lifecycle values are:
-
-| Status | Typical stages |
-|--------|----------------|
-| `accepted` | `queued` |
-| `running` | `loading_skill`, `collecting_context`, `agent`, `rendering` |
-| `committing` | `writing`, `refreshing`, `salvaging` |
-| `cancelling` | Settling in-process work and resource cleanup |
-| `completed` | `completed`, `salvaged` |
-| `failed` | Stage where the failure occurred; the response contains `error.code` and `error.message` |
-| `cancelled` | `cancelled` |
-
### feedback()
Submit explicit feedback for an existing assistant response.
@@ -320,7 +179,7 @@ A missing target response returns `404`. Rating feedback without `feedback_score
## Client Scope
-The standard OpenViking Python, TypeScript, and Go SDKs do not currently wrap the Bot proxy. Chat and Compile are available through the `ov` CLI and HTTP. The VikingBot Gateway also exposes Session and Channel APIs; see the [VikingBot documentation](https://github.com/volcengine/OpenViking/blob/main/bot/README.md#http-api).
+The standard OpenViking Python, TypeScript, and Go SDKs do not currently wrap the Bot proxy. Chat is available through the `ov` CLI and HTTP. The VikingBot Gateway also exposes Session and Channel APIs; see the [VikingBot documentation](https://github.com/volcengine/OpenViking/blob/main/bot/README.md#http-api).
## Related Documentation
diff --git a/docs/en/configuration/01-server.md b/docs/en/configuration/01-server.md
index b7842e8b2..fb1e0989b 100644
--- a/docs/en/configuration/01-server.md
+++ b/docs/en/configuration/01-server.md
@@ -57,6 +57,7 @@ Optional sections use their defaults when omitted. Unknown fields are rejected.
| `parsers` | object | parser defaults | PDF, code, image, audio, video, and text parsing |
| `semantic` | object | built-in defaults | Abstract and overview generation limits |
| `parser_api` | object | disabled | Third-party file parser API |
+| `compile_api` | object | disabled | External Compile task API |
| `connector` | object | disabled | External Connector ingestion service |
| `encryption` | object | disabled | File and secret encryption |
| `git` | object | local | Version backend: `local` or `s3` |
@@ -225,6 +226,23 @@ This setting controls queue-job concurrency. It is separate from `vlm.media.max_
|---|---|---:|---|
| `max_concurrent` | integer | `8` | Number of SessionCommit jobs consumed concurrently; must be greater than `0`; requires a server restart after changes |
+### `queue_workers.external_task`
+
+| Field | Type | Default | Description |
+|---|---|---:|---|
+| `max_concurrent` | integer | `10` | Number of external asynchronous tasks consumed concurrently; must be greater than `0`; requires a server restart after changes |
+
+## Compile API Settings
+
+| Field | Type | Default | Description |
+|---|---|---:|---|
+| `base_url` | string | `""` | External service base URL, including `http://` or `https://`; a non-empty value enables external Compile |
+| `gateway_token` | string | `""` | Optional service credential used by OV to call the Compile Gateway |
+| `http_timeout_seconds` | number | `10` | Timeout for one HTTP request |
+| `poll_interval_ms` | integer | `30000` | External task polling interval |
+
+When `base_url` is configured, OV sends the current user's OV API key in `X-API-Key`. It sends `X-Gateway-Token` only when `gateway_token` is configured.
+
## Reindex Settings
### `reindex`
diff --git a/docs/en/context-compilation/01-overview.md b/docs/en/context-compilation/01-overview.md
index 9b1270429..5e95c0856 100644
--- a/docs/en/context-compilation/01-overview.md
+++ b/docs/en/context-compilation/01-overview.md
@@ -23,11 +23,10 @@ ov compile \
--from viking://resources/research \
--to viking://resources/research-wiki \
--skill viking://agent/skills/llm-wiki \
- --reason "Organize the research into a knowledge base the team can search" \
- --wait
+ --reason "Organize the research into a knowledge base the team can search"
```
-`--wait` polls until the task reaches a terminal state; drop it to get a `cmp_...` task ID back immediately, then use `ov task status <id>` to check progress and `ov task cancel <id>` to stop it. Full field reference, task lifecycle, and HTTP API are in [VikingBot API → compile()](../api/24-vikingbot.md#compile).
+The command returns a `cmp_...` task ID immediately. Use `ov task status <id>` to check progress and `ov task cancel <id>` to stop it. The full field reference, task lifecycle, and HTTP API are in the [Agent Runtime API](../api/23-agent-runtime.md).
## Swap the Skill, get a different output
@@ -51,5 +50,5 @@ The first two examples also give the complete `ov` commands from **importing sou
## Related docs
- [VikingBot concepts](../concepts/15-vikingbot.md) — the runtime behind Compile
-- [VikingBot API](../api/24-vikingbot.md) — full reference for `compile()` / `compile_status()` / `compile_cancel()`
+- [Agent Runtime API](../api/23-agent-runtime.md) — full reference for creating, inspecting, and cancelling Compile tasks
- [Skills API](../api/04-skills.md) — managing and customizing Skills
diff --git a/docs/en/context-compilation/02-llm-wiki.md b/docs/en/context-compilation/02-llm-wiki.md
index 844e227a2..9c7fbc160 100644
--- a/docs/en/context-compilation/02-llm-wiki.md
+++ b/docs/en/context-compilation/02-llm-wiki.md
@@ -59,13 +59,12 @@ ov compile \
--from viking://resources/research \
--to viking://resources/research-wiki \
--skill viking://agent/skills/llm-wiki \
- --reason "Organize into a team-searchable Wiki, keeping the source of every claim" \
- --wait
+ --reason "Organize into a team-searchable Wiki, keeping the source of every claim"
```
- `--from` can be repeated or comma-separated to pass multiple sources at once.
- The `--to` directory is created automatically if it does not exist.
-- Add `-o json` for machine-readable output; drop `--wait` to avoid blocking and poll with the returned `task_id`:
+- Add `-o json` for machine-readable output. The command returns a `task_id` immediately; use it to inspect or cancel the task:
```bash
ov task status cmp_01abc # progress and final result
@@ -128,4 +127,4 @@ python examples/compile/graph-show/llm-wiki/wiki_graph.py \
- [Context Compilation Overview](./01-overview.md)
- [Knowledge Graph example](./03-knowledge-graph.md)
-- [VikingBot API → compile()](../api/24-vikingbot.md#compile)
+- [Agent Runtime API](../api/23-agent-runtime.md)
diff --git a/docs/en/context-compilation/03-knowledge-graph.md b/docs/en/context-compilation/03-knowledge-graph.md
index ff3d56651..defac4db0 100644
--- a/docs/en/context-compilation/03-knowledge-graph.md
+++ b/docs/en/context-compilation/03-knowledge-graph.md
@@ -40,11 +40,10 @@ ov compile \
--from viking://resources/journal \
--to viking://resources/journal-kg \
--skill viking://agent/skills/knowledge-graph \
- --reason "Extract characters, places, artifacts and their relationships into a traversable graph" \
- --wait
+ --reason "Extract characters, places, artifacts and their relationships into a traversable graph"
```
-Drop `--wait` to get a `task_id` back immediately, then:
+The command returns a `task_id` immediately. Then:
```bash
ov task status cmp_01abc # progress and final result
@@ -103,4 +102,4 @@ Open `journal-kg.html` in a browser. The script validates first — `relations.j
- [Context Compilation Overview](./01-overview.md)
- [LLM Wiki example](./02-llm-wiki.md)
-- [VikingBot API → compile()](../api/24-vikingbot.md#compile)
+- [Agent Runtime API](../api/23-agent-runtime.md)
diff --git a/docs/en/context-compilation/04-daily-report.md b/docs/en/context-compilation/04-daily-report.md
index 6d23c1c21..2dfbc37d5 100644
--- a/docs/en/context-compilation/04-daily-report.md
+++ b/docs/en/context-compilation/04-daily-report.md
@@ -30,8 +30,7 @@ ov compile \
--from viking://resources/work-logs \
--to viking://resources/daily-report \
--skill viking://agent/skills/daily-report \
- --reason "Daily report for 2026-08-20, focused on my outcomes and decisions" \
- --wait
+ --reason "Daily report for 2026-08-20, focused on my outcomes and decisions"
```
For several days at once, put the date range in `--reason` (each day is still its own page):
@@ -41,11 +40,10 @@ ov compile \
--from viking://resources/work-logs \
--to viking://resources/daily-report \
--skill viking://agent/skills/daily-report \
- --reason "One daily report per day for 2026-08-18 to 2026-08-20" \
- --wait
+ --reason "One daily report per day for 2026-08-18 to 2026-08-20"
```
-Drop `--wait` to get a `task_id` back immediately:
+The command returns a `task_id` immediately:
```bash
ov task status cmp_01abc # progress and final result
@@ -66,4 +64,4 @@ ov read viking://resources/daily-report/2026-08-20.md
- [Context Compilation Overview](./01-overview.md)
- [Knowledge Distillation example](./05-knowledge-distillation.md)
-- [VikingBot API → compile()](../api/24-vikingbot.md#compile)
+- [Agent Runtime API](../api/23-agent-runtime.md)
diff --git a/docs/en/context-compilation/05-knowledge-distillation.md b/docs/en/context-compilation/05-knowledge-distillation.md
index 8a37bfa54..6dae1d795 100644
--- a/docs/en/context-compilation/05-knowledge-distillation.md
+++ b/docs/en/context-compilation/05-knowledge-distillation.md
@@ -44,8 +44,7 @@ ov compile \
--from viking://resources/finance-reports \
--to viking://resources/finance-insights \
--skill viking://agent/skills/knowledge-distillation \
- --reason "Compare the last three years of reports; obtain changes and drivers in revenue quality, profitability, and risk" \
- --wait
+ --reason "Compare the last three years of reports; obtain changes and drivers in revenue quality, profitability, and risk"
```
`--from` accepts multiple sources for cross-knowledge-base comparison:
@@ -55,11 +54,10 @@ ov compile \
--from viking://resources/finance-2024,viking://resources/finance-2025 \
--to viking://resources/finance-insights \
--skill viking://agent/skills/knowledge-distillation \
- --reason "Compare the two yearly knowledge bases; surface changes and structural differences in key metrics" \
- --wait
+ --reason "Compare the two yearly knowledge bases; surface changes and structural differences in key metrics"
```
-Drop `--wait` to get a `task_id` back immediately:
+The command returns a `task_id` immediately:
```bash
ov task status cmp_01abc # progress and final result
@@ -81,4 +79,4 @@ By default **no `index.md` is created** — a distillation is itself a set of co
- [Context Compilation Overview](./01-overview.md)
- [Daily Report example](./04-daily-report.md)
-- [VikingBot API → compile()](../api/24-vikingbot.md#compile)
+- [Agent Runtime API](../api/23-agent-runtime.md)
diff --git a/docs/zh/api/01-overview.md b/docs/zh/api/01-overview.md
index 2e821db6a..d4d8b0049 100644
--- a/docs/zh/api/01-overview.md
+++ b/docs/zh/api/01-overview.md
@@ -460,6 +460,7 @@ JSON 输出 - 错误:
| 方法 | 路径 | 说明 |
|------|------|------|
+| POST | `/api/v1/compile` | 创建由 OV 托管的 Compile 任务 |
| GET | `/api/v1/tasks/{task_id}` | 获取后台任务 |
| POST | `/api/v1/tasks/{task_id}/cancel` | 取消后台任务 |
| GET | `/api/v1/tasks` | 列出后台任务 |
@@ -505,7 +506,7 @@ JSON 输出 - 错误:
| POST | `/api/v1/privacy-configs/{category}/{target_key}` | 写入并激活新版本 |
| POST | `/api/v1/privacy-configs/{category}/{target_key}/activate` | 激活指定版本 |
-### [OpenViking Assets](22-openviking-assets.md)、[WebDAV](20-webdav.md) 与 [VikingBot API](24-vikingbot.md)
+### [OpenViking Assets](22-openviking-assets.md)、[WebDAV](20-webdav.md)、[Agent Runtime API](23-agent-runtime.md) 与 [VikingBot API](24-vikingbot.md)
| 方法 | 路径 | 说明 |
|------|------|------|
@@ -518,13 +519,14 @@ JSON 输出 - 错误:
| DELETE | `/webdav/resources`、`/webdav/resources/{resource_path}` | 删除文件或目录 |
| MKCOL | `/webdav/resources`、`/webdav/resources/{resource_path}` | 创建目录 |
| MOVE | `/webdav/resources`、`/webdav/resources/{resource_path}` | 移动或重命名资源 |
+| POST | `/api/v1/compile` | 创建异步 Compile 任务 |
| GET | `/bot/v1/health` | VikingBot 健康检查 |
| POST | `/bot/v1/chat` | VikingBot 非流式对话 |
| POST | `/bot/v1/chat/stream` | VikingBot 流式对话 |
| POST | `/bot/v1/feedback` | 提交 VikingBot 回答反馈 |
-| POST | `/bot/v1/compile` | 启动 Skill 驱动的 Compile 任务 |
-| GET | `/bot/v1/compile/{task_id}` | 获取 Compile 任务状态 |
-| POST | `/bot/v1/compile/{task_id}/cancel` | 取消 Compile 任务 |
+| POST | `/bot/v1/compile` | 已停用;返回新接口迁移提示 |
+| GET | `/bot/v1/compile/{task_id}` | 已停用;返回 Task 接口迁移提示 |
+| POST | `/bot/v1/compile/{task_id}/cancel` | 已停用;返回 Task 取消接口迁移提示 |
---
@@ -539,4 +541,4 @@ JSON 输出 - 错误:
| 数据生命周期 | Watch、快照、OVPack |
| 运维与观测 | 系统、任务、Observer、Metrics |
| 身份与治理 | 管理员、ACL、隐私配置 |
-| 协议与扩展 | OpenViking Assets、WebDAV、VikingBot API |
+| 协议与扩展 | OpenViking Assets、WebDAV、Agent Runtime API、VikingBot API |
diff --git a/docs/zh/api/23-agent-runtime.md b/docs/zh/api/23-agent-runtime.md
new file mode 100644
index 000000000..476fa5c29
--- /dev/null
+++ b/docs/zh/api/23-agent-runtime.md
@@ -0,0 +1,224 @@
+# Agent Runtime API
+
+Agent Runtime Server 负责执行 Agent 任务,当前支持 Compile。应用通过 OpenViking 的 Compile API 提交任务,OpenViking 负责校验请求、持久化任务和管理生命周期,再调用 Runtime 执行接口;内置 VikingBot 也实现了同一执行协议,可用于本地部署。
+
+**代码入口**:
+
+- `openviking/server/routers/compile.py` - 创建 Compile 任务
+- `openviking/server/routers/tasks.py` - 查询和取消任务
+- `openviking/service/compile_service.py` - Runtime 调用与任务状态收敛
+
+## Compile 任务接口
+
+### 创建任务
+
+| 字段 | 类型 | 必填 | 默认值 | 说明 |
+|------|------|------|--------|------|
+| `from` | string[] | 是 | - | 一个或多个来源目录 |
+| `to` | string | 是 | - | 目标 Resource 或 Memory 目录,或受支持的 Skill namespace |
+| `skill` | string | 是 | - | Skill 目录或其 `SKILL.md` URI |
+| `reason` | string | 否 | Skill 驱动的默认值 | 本次 Compile 的补充指令 |
+| `args` | object | 否 | - | 执行端扩展参数;`model_name` 可传模型 Endpoint ID |
+
+`args` 整体可省略,模型 Endpoint ID 也不是顶层字段。需要指定模型时使用 `args.model_name`;不传时由执行端使用其默认模型配置。
+
+**HTTP API**
+
+```http
+POST /api/v1/compile
+```
+
+```bash
+curl -X POST http://localhost:1933/api/v1/compile \
+ -H "Content-Type: application/json" \
+ -H "X-API-Key: your-key" \
+ -d '{
+ "from": ["viking://resources/research"],
+ "to": "viking://resources/research-wiki",
+ "skill": "viking://user/default/skills/research-compiler",
+ "reason": "追踪历史进展,并保留支撑证据。",
+ "args": {"model_name": "your-model-endpoint-id"}
+ }'
+```
+
+接口返回 `202 Accepted` 和 OV TaskRecord:
+
+```json
+{
+ "status": "ok",
+ "result": {
+ "task_id": "cmp_01abc",
+ "task_type": "compile",
+ "status": "pending",
+ "stage": "queued",
+ "resource_id": "viking://resources/research"
+ }
+}
+```
+
+**CLI**
+
+```bash
+ov compile \
+ --from viking://resources/research \
+ --to viking://resources/research-wiki \
+ --skill viking://user/default/skills/research-compiler \
+ --reason "追踪历史进展,并保留支撑证据。" \
+ --args '{"model_name":"your-model-endpoint-id"}'
+```
+
+`--args` 必须是 JSON object。命令提交后立即返回 Task ID。
+
+**SDK**
+
+Python、TypeScript 和 Go SDK 都通过各自的 Compile options 传递 `reason` 和 `args`:
+
+::: code-group
+
+```python [Python]
+task = client.compile(
+ ["viking://resources/research"],
+ "viking://resources/research-wiki",
+ "viking://user/default/skills/research-compiler",
+ {"args": {"model_name": "your-model-endpoint-id"}},
+)
+```
+
+```ts [TypeScript]
+const task = await client.compile(
+ ["viking://resources/research"],
+ "viking://resources/research-wiki",
+ "viking://user/default/skills/research-compiler",
+ { args: { model_name: "your-model-endpoint-id" } },
+);
+```
+
+```go [Go]
+task, err := client.Compile(
+ ctx,
+ []string{"viking://resources/research"},
+ "viking://resources/research-wiki",
+ "viking://user/default/skills/research-compiler",
+ &openviking.CompileOptions{
+ Args: map[string]any{"model_name": "your-model-endpoint-id"},
+ },
+)
+```
+
+:::
+
+### 查询任务
+
+任务仅对创建它的 principal 可见;任务不存在或属于其他 principal 时均返回 `404`。
+
+```http
+GET /api/v1/tasks/{task_id}
+```
+
+```bash
+ov task status cmp_01abc
+```
+
+任务进入终态后,响应还会包含结果或错误。
+
+### 取消任务
+
+```http
+POST /api/v1/tasks/{task_id}/cancel
+```
+
+```bash
+ov task cancel cmp_01abc
+```
+
+任务会先进入 `cancelling`,待当前进程内工作和清理完成后进入 `cancelled`;已经完成的写入不会回滚。重复取消已经 `cancelled` 的任务是幂等的。
+
+| Status | 常见 Stage |
+|--------|------------|
+| `pending` | `queued` |
+| `running` | 执行端返回的执行 Stage,例如 `agent`、`writing` |
+| `cancelling` | 收敛当前进程内工作和清理资源 |
+| `completed` | `completed`、`salvaged` |
+| `failed` | 失败发生时的 Stage;响应包含 `error` |
+| `cancelled` | `cancelled` |
+
+### 旧接口
+
+OV 上的以下旧 VikingBot 代理路由已经停用,只返回迁移提示:
+
+```http
+POST /bot/v1/compile
+GET /bot/v1/compile/{task_id}
+POST /bot/v1/compile/{task_id}/cancel
+```
+
+创建任务使用 `/api/v1/compile`,查询和取消统一使用 `/api/v1/tasks/{task_id}`。
+
+## Runtime 执行接口
+
+以下接口由 `compile_api.base_url` 指向的执行服务提供,供 OV 调用。应用通过前述 Compile API 提交任务。
+
+### 创建执行任务
+
+```http
+POST /runtime/v1/tasks
+Idempotency-Key: <OV task_id>
+```
+
+```json
+{
+ "task_type": "compile",
+ "payload": {
+ "from": ["viking://resources/research"],
+ "to": "viking://resources/research-wiki",
+ "skill": "viking://agent/skills/wiki",
+ "reason": "整理成知识库",
+ "args": {"model_name": "your-model-endpoint-id"}
+ }
+}
+```
+
+`task_type` 和 `payload` 均必填。当前只支持 `task_type="compile"`;`payload` 使用本页创建任务的字段及校验规则,`reason`、`args` 可省略。内置 VikingBot 不支持非空 `args`。不支持的类型或无效的 payload 返回 `4xx`,不创建执行任务。
+
+OV 通过 `X-API-Key` 传递当前用户的 OV API Key;配置 `compile_api.gateway_token` 时还会发送 `X-Gateway-Token`。这些凭证不能出现在公开任务结果中。
+
+接受请求后返回 `202 Accepted`,响应包含执行端标识:
+
+```json
+{"session_id": "session-123"}
+```
+
+同一用户的相同 `Idempotency-Key` 必须返回同一个 `session_id`,不能重复执行。`session_id` 用于执行端查询和取消;应用查询 OV 任务时使用 `task_id`。
+
+### 查询与取消执行任务
+
+```http
+POST /runtime/v1/tasks/status
+POST /runtime/v1/tasks/cancel
+```
+
+两个接口均使用以下请求体:
+
+```json
+{"session_id": "session-123"}
+```
+
+两个接口均返回执行状态,例如:
+
+```json
+{
+ "status": "running",
+ "stage": "compile: agent",
+ "error": null,
+ "meta": {},
+ "result": null
+}
+```
+
+`status` 可为 `pending`、`running`、`cancelling`、`completed`、`failed` 或 `cancelled`。取消请求可以先返回 `cancelling`,实际执行停止并完成清理后再返回 `cancelled`;重复取消已结束任务返回其当前终态。查询和取消均须校验任务归属。
+
+## 相关文档
+
+- [后台任务](17-tasks.md) - 通用任务查询、取消和列表接口
+- [上下文编译](../context-compilation/01-overview.md) - Compile 使用场景和示例
+- [Skills API](04-skills.md) - 管理 Compile 使用的 Skill
diff --git a/docs/zh/api/24-vikingbot.md b/docs/zh/api/24-vikingbot.md
index 1313ecd2d..8e9d0c0b1 100644
--- a/docs/zh/api/24-vikingbot.md
+++ b/docs/zh/api/24-vikingbot.md
@@ -132,147 +132,6 @@ data: {"event":"response","data":{"content":"当前知识库包含……","respo
`event` 可能为 `reasoning`、`reasoning_delta`、`tool_call`、`tool_result`、`content_delta`、`iteration` 或 `response`。
-### compile()
-
-启动一个异步、由 Skill 驱动的 Compile 任务。VikingBot 会加载指定 Skill,使用当前认证用户身份读取来源目录,在任务独立的 AgentLoop 中执行,并将通过校验的产物提交到目标 URI 下。
-
-| 字段 | 类型 | 必填 | 默认值 | 说明 |
-|------|------|------|--------|------|
-| `from` | string[] | 是 | - | 一个或多个来源目录 |
-| `to` | string | 是 | - | 目标 Resource 或 Memory 目录,或受支持的 Skill namespace |
-| `skill` | string | 是 | - | Skill 目录或其 `SKILL.md` URI |
-| `reason` | string | 否 | Skill 驱动的默认值 | 本次 Compile 的补充指令 |
-| `runtime_timeout_seconds` | number | 否 | 3600 | 正数且有限,且不得超过服务端最大运行时限(默认 3600 秒) |
-
-**HTTP API**
-
-```
-POST /bot/v1/compile
-```
-
-```bash
-curl -X POST http://localhost:1933/bot/v1/compile \
- -H "Content-Type: application/json" \
- -H "X-API-Key: your-key" \
- -d '{
- "from": ["viking://resources/research"],
- "to": "viking://resources/research-wiki",
- "skill": "viking://user/default/skills/research-compiler",
- "reason": "追踪历史进展,并保留支撑证据。"
- }'
-```
-
-**CLI**
-
-```bash
-ov compile \
- --from viking://resources/research \
- --to viking://resources/research-wiki \
- --skill viking://user/default/skills/research-compiler \
- --reason "追踪历史进展,并保留支撑证据。" \
- --wait
-```
-
-`--wait` 会轮询状态接口,直到任务进入终态。`--timeout` 只限制本地等待时间,不会取消服务端任务;`--runtime-timeout` 用于设置本次任务的 `runtime_timeout_seconds`,只能缩短服务端拥有的最大运行时限,超限请求会以 `429 RESOURCE_EXHAUSTED` 拒绝。在 Agent 执行期间达到该时限,或达到配置的 AgentLoop 迭代上限(`bot.agents.max_tool_iterations`,默认 50)时,会在独立的短 grace period 内尝试保存符合条件的 Resource 阶段性产物;没有可保存产物时任务失败,非 Resource 目标以及后续阶段超时不使用该 fallback。
-
-`direct` backend 会以 Bot 宿主机权限执行 Compile 的 `exec` 命令。`bot.sandbox.backends.direct.allow_compile_exec` 默认为 `true`:Compile 工具链开源,`exec` 默认直接以用户 shell 权限运行,普通 Wiki 和产物文件整理仍通过文件工具运行。声明了 `requires.bins` 或 `requires.env` 的 Skill 仍会先探测命令;将该选项设为 `false` 时 Compile 不会暴露 `exec`,此类 Skill 会在执行任何命令探测前以 `SKILL_CAPABILITY_UNAVAILABLE` 失败。依赖 CLI 的 Skill 推荐使用具备文件系统和网络策略的隔离 backend。超过 admission 上限时返回 `429 RESOURCE_EXHAUSTED`。
-
-**响应示例**
-
-HTTP 接口返回 `202 Accepted`:
-
-```json
-{
- "status": "ok",
- "result": {
- "task_id": "cmp_01abc",
- "status": "accepted",
- "to": "viking://resources/research-wiki"
- }
-}
-```
-
-### compile_status()
-
-获取任务当前状态;任务进入终态后还会返回结果或错误。任务仅对创建它的 principal 可见;任务不存在或属于其他 principal 时均返回 `404`。
-
-**HTTP API**
-
-```
-GET /bot/v1/compile/{task_id}
-```
-
-```bash
-curl http://localhost:1933/bot/v1/compile/cmp_01abc \
- -H "X-API-Key: your-key"
-```
-
-CLI 可直接使用 Compile 返回的 `cmp_...` task ID:
-
-```bash
-ov task status cmp_01abc
-```
-
-**响应示例**
-
-```json
-{
- "status": "ok",
- "result": {
- "task_id": "cmp_01abc",
- "status": "completed",
- "stage": "completed",
- "created_at": "2026-07-28T08:00:00Z",
- "updated_at": "2026-07-28T08:02:30Z",
- "result": {
- "from": ["viking://resources/research"],
- "to": "viking://resources/research-wiki",
- "skill": "viking://user/default/skills/research-compiler",
- "okf_version": "0.1",
- "created": ["viking://resources/research-wiki/Progress.md"],
- "updated": [],
- "unchanged": [],
- "page_count": 1,
- "link_count": 0,
- "warnings": []
- }
- }
-}
-```
-
-### compile_cancel()
-
-按 task ID 请求协作式停止 Compile 任务。任务会先进入 `cancelling`,待当前进程内工作和清理完成后进入 `cancelled`;已经完成的写入不会回滚。重复取消已经 `cancelled` 的任务是幂等的,任务不存在或属于其他 principal 时返回 `404`。
-
-**CLI**
-
-```bash
-ov task cancel cmp_01abc
-```
-
-**HTTP API**
-
-```http
-POST /bot/v1/compile/{task_id}/cancel
-```
-
-```bash
-curl -X POST http://localhost:1933/bot/v1/compile/cmp_01abc/cancel \
- -H "X-API-Key: your-key"
-```
-
-任务生命周期如下:
-
-| Status | 常见 Stage |
-|--------|------------|
-| `accepted` | `queued` |
-| `running` | `loading_skill`、`collecting_context`、`agent`、`rendering` |
-| `committing` | `writing`、`refreshing`、`salvaging` |
-| `cancelling` | 收敛当前进程内工作和清理资源 |
-| `completed` | `completed`、`salvaged` |
-| `failed` | 失败发生时的 Stage;响应包含 `error.code` 和 `error.message` |
-| `cancelled` | `cancelled` |
-
### feedback()
对已经生成的回复提交显式反馈。
@@ -317,7 +176,7 @@ curl -X POST http://localhost:1933/bot/v1/feedback \
## 客户端范围
-标准 OpenViking Python、TypeScript 和 Go SDK 当前不封装 Bot 代理接口;Chat 和 Compile 可通过 `ov` CLI 与 HTTP 使用。VikingBot Gateway 自身还提供 Session 和 Channel API,详见 [VikingBot 文档](https://github.com/volcengine/OpenViking/blob/main/bot/README_CN.md#http-api)。
+标准 OpenViking Python、TypeScript 和 Go SDK 当前不封装 Bot 代理接口;Chat 可通过 `ov` CLI 与 HTTP 使用。VikingBot Gateway 自身还提供 Session 和 Channel API,详见 [VikingBot 文档](https://github.com/volcengine/OpenViking/blob/main/bot/README_CN.md#http-api)。
## 相关文档
diff --git a/docs/zh/configuration/01-server.md b/docs/zh/configuration/01-server.md
index 3345f02f7..c4a78f9b4 100644
--- a/docs/zh/configuration/01-server.md
+++ b/docs/zh/configuration/01-server.md
@@ -57,6 +57,7 @@ openviking-server --config /path/to/ov.conf
| `parsers` | object | 各解析器默认值 | PDF、代码、图片、音视频等解析行为 |
| `semantic` | object | 内置默认值 | abstract 和 overview 的生成限制 |
| `parser_api` | object | disabled | 第三方文件解析 API |
+| `compile_api` | object | disabled | 外部 Compile 任务 API |
| `connector` | object | disabled | 外部 Connector 数据导入服务 |
| `encryption` | object | disabled | 文件和敏感字段加密 |
| `git` | object | local | 版本管理后端,可使用 `local` 或 `s3` |
@@ -225,6 +226,23 @@ Search 和 Find 请求的默认 `limit` 为 `10`,可以在每次 API 或 SDK
|---|---|---:|---|
| `max_concurrent` | integer | `8` | 同时消费的 SessionCommit 作业数,必须大于 `0`;修改后需重启服务 |
+### `queue_workers.external_task`
+
+| 字段 | 类型 | 默认值 | 说明 |
+|---|---|---:|---|
+| `max_concurrent` | integer | `10` | 同时消费的外部异步任务数,必须大于 `0`;修改后需重启服务 |
+
+## Compile API 配置
+
+| 字段 | 类型 | 默认值 | 说明 |
+|---|---|---:|---|
+| `base_url` | string | `""` | 外部服务地址,必须包含 `http://` 或 `https://`;非空即启用外部 Compile |
+| `gateway_token` | string | `""` | OV 调用 Compile Gateway 使用的可选服务凭证 |
+| `http_timeout_seconds` | number | `10` | 单次 HTTP 请求超时 |
+| `poll_interval_ms` | integer | `30000` | 外部任务状态轮询间隔 |
+
+配置 `base_url` 后,OV 通过 `X-API-Key` 传递当前用户的 OV API Key;仅在配置 `gateway_token` 时发送 `X-Gateway-Token`。
+
## Reindex 配置
### `reindex`
diff --git a/docs/zh/context-compilation/01-overview.md b/docs/zh/context-compilation/01-overview.md
index 4c0ca651b..4fb84f1f9 100644
--- a/docs/zh/context-compilation/01-overview.md
+++ b/docs/zh/context-compilation/01-overview.md
@@ -23,11 +23,10 @@ ov compile \
--from viking://resources/research \
--to viking://resources/research-wiki \
--skill viking://agent/skills/llm-wiki \
- --reason "把研究资料整理成便于团队检索的知识库" \
- --wait
+ --reason "把研究资料整理成便于团队检索的知识库"
```
-`--wait` 会一直轮询到任务结束;去掉它就立刻返回一个 `cmp_...` 任务 ID,之后用 `ov task status <id>` 查看进度、用 `ov task cancel <id>` 取消。完整的字段说明、任务生命周期和 HTTP 接口见 [VikingBot API → compile()](../api/24-vikingbot.md#compile)。
+命令会立即返回一个 `cmp_...` 任务 ID,之后用 `ov task status <id>` 查看进度、用 `ov task cancel <id>` 取消。完整的字段说明、任务生命周期和 HTTP 接口见 [Agent Runtime API](../api/23-agent-runtime.md)。
## 换个 Skill,就换一种产物
@@ -51,5 +50,5 @@ Compile 本身不规定「编译成什么」——那由 Skill 决定。同一
## 相关文档
- [VikingBot 概念](../concepts/15-vikingbot.md) — Compile 背后的执行体
-- [VikingBot API](../api/24-vikingbot.md) — `compile()` / `compile_status()` / `compile_cancel()` 的完整参考
+- [Agent Runtime API](../api/23-agent-runtime.md) — 创建、查询和取消 Compile 任务的完整参考
- [Skills API](../api/04-skills.md) — 如何管理和自定义 Skill
diff --git a/docs/zh/context-compilation/02-llm-wiki.md b/docs/zh/context-compilation/02-llm-wiki.md
index 27b24898d..1a8dc6bf7 100644
--- a/docs/zh/context-compilation/02-llm-wiki.md
+++ b/docs/zh/context-compilation/02-llm-wiki.md
@@ -59,13 +59,12 @@ ov compile \
--from viking://resources/research \
--to viking://resources/research-wiki \
--skill viking://agent/skills/llm-wiki \
- --reason "面向团队检索整理成 Wiki,保留每条结论的出处" \
- --wait
+ --reason "面向团队检索整理成 Wiki,保留每条结论的出处"
```
- `--from` 可以重复或用逗号分隔,一次传多个来源。
- `--to` 目录不存在时会自动创建。
-- 想要机器可读结果加 `-o json`;不想阻塞终端就去掉 `--wait`,用返回的 `task_id` 轮询:
+- 想要机器可读结果加 `-o json`;命令会立即返回 `task_id`,用它查询或取消任务:
```bash
ov task status cmp_01abc # 查看进度与最终结果
@@ -128,4 +127,4 @@ python examples/compile/graph-show/llm-wiki/wiki_graph.py \
- [上下文编译概览](./01-overview.md)
- [Knowledge Graph 示例](./03-knowledge-graph.md)
-- [VikingBot API → compile()](../api/24-vikingbot.md#compile)
+- [Agent Runtime API](../api/23-agent-runtime.md)
diff --git a/docs/zh/context-compilation/03-knowledge-graph.md b/docs/zh/context-compilation/03-knowledge-graph.md
index d2531ca12..6a47939bb 100644
--- a/docs/zh/context-compilation/03-knowledge-graph.md
+++ b/docs/zh/context-compilation/03-knowledge-graph.md
@@ -40,11 +40,10 @@ ov compile \
--from viking://resources/journal \
--to viking://resources/journal-kg \
--skill viking://agent/skills/knowledge-graph \
- --reason "抽取人物、地点、法宝及其关系,构建可遍历的知识图谱" \
- --wait
+ --reason "抽取人物、地点、法宝及其关系,构建可遍历的知识图谱"
```
-去掉 `--wait` 会立刻返回 `task_id`,之后:
+命令会立刻返回 `task_id`,之后:
```bash
ov task status cmp_01abc # 查看进度与最终结果
@@ -103,4 +102,4 @@ python examples/compile/graph-show/knowledge-graph/knowledge_graph.py \
- [上下文编译概览](./01-overview.md)
- [LLM Wiki 示例](./02-llm-wiki.md)
-- [VikingBot API → compile()](../api/24-vikingbot.md#compile)
+- [Agent Runtime API](../api/23-agent-runtime.md)
diff --git a/docs/zh/context-compilation/04-daily-report.md b/docs/zh/context-compilation/04-daily-report.md
index 5862f1398..5ca8f6eca 100644
--- a/docs/zh/context-compilation/04-daily-report.md
+++ b/docs/zh/context-compilation/04-daily-report.md
@@ -30,8 +30,7 @@ ov compile \
--from viking://resources/work-logs \
--to viking://resources/daily-report \
--skill viking://agent/skills/daily-report \
- --reason "生成 2026-08-20 的日报,聚焦我的工作产出与决策" \
- --wait
+ --reason "生成 2026-08-20 的日报,聚焦我的工作产出与决策"
```
一次生成多天,把日期范围写进 `--reason` 即可(每天仍是独立一页):
@@ -41,11 +40,10 @@ ov compile \
--from viking://resources/work-logs \
--to viking://resources/daily-report \
--skill viking://agent/skills/daily-report \
- --reason "生成 2026-08-18 至 2026-08-20 每天一份日报" \
- --wait
+ --reason "生成 2026-08-18 至 2026-08-20 每天一份日报"
```
-去掉 `--wait` 会立刻返回 `task_id`:
+命令会立刻返回 `task_id`:
```bash
ov task status cmp_01abc # 查看进度与最终结果
@@ -66,4 +64,4 @@ ov read viking://resources/daily-report/2026-08-20.md
- [上下文编译概览](./01-overview.md)
- [知识蒸馏示例](./05-knowledge-distillation.md)
-- [VikingBot API → compile()](../api/24-vikingbot.md#compile)
+- [Agent Runtime API](../api/23-agent-runtime.md)
diff --git a/docs/zh/context-compilation/05-knowledge-distillation.md b/docs/zh/context-compilation/05-knowledge-distillation.md
index 85f29c9a9..955079c78 100644
--- a/docs/zh/context-compilation/05-knowledge-distillation.md
+++ b/docs/zh/context-compilation/05-knowledge-distillation.md
@@ -44,8 +44,7 @@ ov compile \
--from viking://resources/finance-reports \
--to viking://resources/finance-insights \
--skill viking://agent/skills/knowledge-distillation \
- --reason "对比近三年财报,找到营收质量、盈利能力和风险的变化及驱动因素" \
- --wait
+ --reason "对比近三年财报,找到营收质量、盈利能力和风险的变化及驱动因素"
```
`--from` 可以传多个来源,用于跨知识库对比:
@@ -55,11 +54,10 @@ ov compile \
--from viking://resources/finance-2024,viking://resources/finance-2025 \
--to viking://resources/finance-insights \
--skill viking://agent/skills/knowledge-distillation \
- --reason "对比两个年度知识库,找出关键指标的变化与结构性差异" \
- --wait
+ --reason "对比两个年度知识库,找出关键指标的变化与结构性差异"
```
-去掉 `--wait` 会立刻返回 `task_id`:
+命令会立刻返回 `task_id`:
```bash
ov task status cmp_01abc # 查看进度与最终结果
@@ -79,4 +77,4 @@ ov read viking://resources/finance-insights/revenue-quality/growth-shifted-from-
- [上下文编译概览](./01-overview.md)
- [日报示例](./04-daily-report.md)
-- [VikingBot API → compile()](../api/24-vikingbot.md#compile)
+- [Agent Runtime API](../api/23-agent-runtime.md)
diff --git a/examples/ov.conf.example b/examples/ov.conf.example
index 9723293e6..4c1cf68a6 100644
--- a/examples/ov.conf.example
+++ b/examples/ov.conf.example
@@ -110,6 +110,13 @@
"file_vectorization_concurrency": 8
},
"session_commit": {"max_concurrent": 8},
+ "external_task": {"max_concurrent": 10},
+ },
+ "compile_api": {
+ "base_url": "",
+ "gateway_token": "",
+ "http_timeout_seconds": 10,
+ "poll_interval_ms": 3000,
},
"reindex": {
"file_vectorization_concurrency": 8
diff --git a/openviking/server/app.py b/openviking/server/app.py
index 04870dc1c..111e31a2f 100644
--- a/openviking/server/app.py
+++ b/openviking/server/app.py
@@ -35,6 +35,7 @@ from openviking.server.routers import (
admin_router,
agent_evolution_router,
bot_router,
+ compile_router,
console_router,
content_router,
debug_router,
@@ -303,6 +304,8 @@ def create_app(
if service is not None:
_configure_session_runtime(service)
+ bot_gateway_token = load_bot_gateway_token() if config.with_bot else ""
+
@asynccontextmanager
async def lifespan(app: FastAPI):
"""Application lifespan handler."""
@@ -312,6 +315,8 @@ def create_app(
service = OpenVikingService()
assert service is not None
+ if config.with_bot:
+ service.compile.configure_local_backend(config.bot_api_url, bot_gateway_token)
_configure_session_runtime(service)
set_service(service)
@@ -610,7 +615,7 @@ def create_app(
import openviking.server.routers.bot as bot_module
bot_module.set_bot_api_url(config.bot_api_url)
- bot_module.set_bot_api_key(load_bot_gateway_token())
+ bot_module.set_bot_api_key(bot_gateway_token)
logger.info(f"Bot API proxy enabled, forwarding to {config.bot_api_url}")
else:
logger.info("Bot API proxy disabled (use --with-bot to enable)")
@@ -620,6 +625,7 @@ def create_app(
app.include_router(acl_router)
app.include_router(admin_router)
app.include_router(agent_evolution_router)
+ app.include_router(compile_router)
app.include_router(resources_router)
app.include_router(filesystem_router)
app.include_router(content_router)
diff --git a/openviking/server/routers/__init__.py b/openviking/server/routers/__init__.py
index e6e80d296..79abd75c4 100644
--- a/openviking/server/routers/__init__.py
+++ b/openviking/server/routers/__init__.py
@@ -6,6 +6,7 @@ from openviking.server.routers.acl import router as acl_router
from openviking.server.routers.admin import router as admin_router
from openviking.server.routers.agent_evolution import router as agent_evolution_router
from openviking.server.routers.bot import router as bot_router
+from openviking.server.routers.compile import router as compile_router
from openviking.server.routers.console import router as console_router
from openviking.server.routers.content import router as content_router
from openviking.server.routers.debug import router as debug_router
@@ -32,6 +33,7 @@ __all__ = [
"admin_router",
"agent_evolution_router",
"bot_router",
+ "compile_router",
"system_router",
"resources_router",
"filesystem_router",
diff --git a/openviking/server/routers/bot.py b/openviking/server/routers/bot.py
index bf34c4e50..69d863c16 100644
--- a/openviking/server/routers/bot.py
+++ b/openviking/server/routers/bot.py
@@ -9,13 +9,11 @@ from typing import AsyncGenerator, Optional
import httpx
from fastapi import APIRouter, Depends, HTTPException, Request, status
-from fastapi.responses import JSONResponse, StreamingResponse
+from fastapi.responses import StreamingResponse
from openviking.server.auth import _auth_mode, get_request_context
from openviking.server.config import get_server_url_from_server_data
from openviking.server.identity import RequestContext
-from openviking.server.models import Response
-from openviking_cli.exceptions import OpenVikingError
from openviking_cli.utils.logger import get_logger
router = APIRouter(prefix="", tags=["bot"])
@@ -134,141 +132,45 @@ def _attach_openviking_connection(
return enriched
-def _bot_gateway_headers(*, connection: dict | None = None) -> dict[str, str]:
- headers = {"Content-Type": "application/json"}
- if BOT_API_KEY:
- headers["X-Gateway-Token"] = BOT_API_KEY
- if connection:
- mapping = {
- "api_key": "X-API-Key",
- "account_id": "X-OpenViking-Account",
- "user_id": "X-OpenViking-User",
- "actor_peer_id": "X-OpenViking-Actor-Peer",
- }
- for field, header in mapping.items():
- value = str(connection.get(field) or "").strip()
- if value:
- headers[header] = value
- return headers
-
-
-def _raise_compile_proxy_error(response: httpx.Response) -> None:
- try:
- payload = response.json()
- except ValueError:
- payload = {}
- detail = payload.get("detail") if isinstance(payload, dict) else None
- if isinstance(detail, dict):
- code = str(detail.get("code") or "UNAVAILABLE")
- message = str(detail.get("message") or "Bot service error")
- else:
- code = "UNAVAILABLE" if response.status_code >= 500 else "INVALID_ARGUMENT"
- message = str(detail or response.text or "Bot service error")
- raise OpenVikingError(message, code=code)
-
-
[email protected]("/compile", status_code=status.HTTP_202_ACCEPTED)
[email protected]("/compile")
async def create_compile(
- request: Request,
_ctx: RequestContext = Depends(get_request_context),
):
- """Create a VikingBot compile task with the authenticated OV identity."""
- bot_url = get_bot_url()
- try:
- body = await request.json()
- except json.JSONDecodeError as exc:
- raise HTTPException(
- status_code=status.HTTP_400_BAD_REQUEST,
- detail="Invalid JSON in request body",
- ) from exc
- enriched = _attach_openviking_connection(
- body,
- request,
- _ctx,
- include_legacy_user_id=False,
- )
- try:
- async with _create_bot_proxy_client() as client:
- response = await client.post(
- f"{bot_url}/bot/v1/compile",
- json=enriched,
- headers=_bot_gateway_headers(),
- timeout=30.0,
- )
- except httpx.RequestError as exc:
- raise HTTPException(
- status_code=status.HTTP_502_BAD_GATEWAY,
- detail=f"Bot service unavailable: {exc}",
- ) from exc
- if not response.is_success:
- _raise_compile_proxy_error(response)
- return JSONResponse(
- status_code=status.HTTP_202_ACCEPTED,
- content=Response(status="ok", result=response.json()).model_dump(mode="json"),
+ raise HTTPException(
+ status_code=status.HTTP_400_BAD_REQUEST,
+ detail=(
+ "This endpoint is no longer supported. Use POST /api/v1/compile, "
+ "then poll GET /api/v1/tasks/{task_id}."
+ ),
)
@router.get("/compile/{task_id}")
async def get_compile(
task_id: str,
- request: Request,
_ctx: RequestContext = Depends(get_request_context),
):
- """Read compile status without exposing tasks owned by another principal."""
- bot_url = get_bot_url()
- connection = _attach_openviking_connection(
- {},
- request,
- _ctx,
- include_legacy_user_id=False,
- ).get("openviking_connection")
- try:
- async with _create_bot_proxy_client() as client:
- response = await client.get(
- f"{bot_url}/bot/v1/compile/{task_id}",
- headers=_bot_gateway_headers(connection=connection),
- timeout=30.0,
- )
- except httpx.RequestError as exc:
- raise HTTPException(
- status_code=status.HTTP_502_BAD_GATEWAY,
- detail=f"Bot service unavailable: {exc}",
- ) from exc
- if not response.is_success:
- _raise_compile_proxy_error(response)
- return Response(status="ok", result=response.json())
+ raise HTTPException(
+ status_code=status.HTTP_400_BAD_REQUEST,
+ detail=(
+ "This endpoint is no longer supported. "
+ "Poll GET /api/v1/tasks/{task_id} instead."
+ ),
+ )
@router.post("/compile/{task_id}/cancel")
async def cancel_compile(
task_id: str,
- request: Request,
_ctx: RequestContext = Depends(get_request_context),
):
- """Cancel a Compile task without exposing tasks owned by another principal."""
- bot_url = get_bot_url()
- connection = _attach_openviking_connection(
- {},
- request,
- _ctx,
- include_legacy_user_id=False,
- ).get("openviking_connection")
- try:
- async with _create_bot_proxy_client() as client:
- response = await client.post(
- f"{bot_url}/bot/v1/compile/{task_id}/cancel",
- json={},
- headers=_bot_gateway_headers(connection=connection),
- timeout=30.0,
- )
- except httpx.RequestError as exc:
- raise HTTPException(
- status_code=status.HTTP_502_BAD_GATEWAY,
- detail=f"Bot service unavailable: {exc}",
- ) from exc
- if not response.is_success:
- _raise_compile_proxy_error(response)
- return Response(status="ok", result=response.json())
+ raise HTTPException(
+ status_code=status.HTTP_400_BAD_REQUEST,
+ detail=(
+ "This endpoint is no longer supported. "
+ "Use POST /api/v1/tasks/{task_id}/cancel instead."
+ ),
+ )
@router.get("/health")
diff --git a/openviking/server/routers/compile.py b/openviking/server/routers/compile.py
new file mode 100644
index 000000000..51ab05dad
--- /dev/null
+++ b/openviking/server/routers/compile.py
@@ -0,0 +1,26 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Compile task creation API."""
+
+from fastapi import APIRouter, Depends, status
+
+from openviking.server.auth import get_request_context
+from openviking.server.dependencies import get_service
+from openviking.server.identity import RequestContext
+from openviking.server.models import Response
+from openviking.service.compile_service import CompileRequest
+
+router = APIRouter(prefix="/api/v1", tags=["compile"])
+
+
[email protected]("/compile", status_code=status.HTTP_202_ACCEPTED)
+async def create_compile(
+ body: CompileRequest,
+ ctx: RequestContext = Depends(get_request_context),
+):
+ connection = {"api_key": ctx.api_key} if ctx.api_key else {}
+ task = await get_service().compile.create(body, connection=connection, ctx=ctx)
+ return Response(status="ok", result=task.to_dict())
+
+
+__all__ = ["router"]
diff --git a/openviking/service/compile_service.py b/openviking/service/compile_service.py
new file mode 100644
index 000000000..a24424e92
--- /dev/null
+++ b/openviking/service/compile_service.py
@@ -0,0 +1,484 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Compile API models and external task provider."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+import httpx
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, model_validator
+
+from openviking.core.namespace import classify_uri, uri_parts
+from openviking.core.path_variables import resolve_path_variables
+from openviking.core.uri_validation import validate_request_viking_uri
+from openviking.server.identity import RequestContext
+from openviking.service.external_task_service import (
+ ExternalTaskError,
+ ExternalTaskService,
+ ExternalTaskSnapshot,
+)
+from openviking.service.fs_service import FSService
+from openviking.service.task_tracker import TaskRecord
+from openviking_cli.exceptions import (
+ InvalidArgumentError,
+ NotFoundError,
+ UnauthenticatedError,
+ UnavailableError,
+)
+from openviking_cli.utils.config.open_viking_config import CompileApiConfig
+
+_ACTIVE_STATUSES = frozenset({"accepted", "pending", "running", "committing"})
+_TERMINAL_STATUSES = frozenset({"completed", "failed", "cancelled"})
+
+
+class CompileRequest(BaseModel):
+ model_config = ConfigDict(extra="forbid", populate_by_name=True)
+
+ from_: list[str] = Field(alias="from", min_length=1)
+ to: str = Field(min_length=1)
+ skill: str = Field(min_length=1)
+ reason: str | None = None
+ args: dict[str, Any] | None = None
+
+ @model_validator(mode="after")
+ def _normalize(self) -> "CompileRequest":
+ sources: list[str] = []
+ for source in self.from_:
+ normalized = source.strip().rstrip("/")
+ if not normalized:
+ raise ValueError("from must not contain empty values")
+ if normalized not in sources:
+ sources.append(normalized)
+ self.from_ = sources
+ self.to = self.to.strip().rstrip("/")
+ self.skill = self.skill.strip().rstrip("/")
+ self.reason = self.reason.strip() if self.reason and self.reason.strip() else None
+ self.args = dict(self.args) if self.args else None
+ if not self.to:
+ raise ValueError("to must not be empty")
+ if not self.skill:
+ raise ValueError("skill must not be empty")
+ return self
+
+
+class CompileErrorInfo(BaseModel):
+ model_config = ConfigDict(extra="ignore")
+
+ code: str
+ message: str
+
+
+class CompileSessionAccepted(BaseModel):
+ model_config = ConfigDict(extra="ignore")
+
+ session_id: str
+
+
+class CompileSessionStatus(BaseModel):
+ model_config = ConfigDict(extra="ignore")
+
+ status: str | None = None
+ stage: str
+ error: CompileErrorInfo | str | None = None
+ meta: dict[str, Any] = Field(default_factory=dict)
+ result: dict[str, Any] | None = None
+
+
+@dataclass(frozen=True)
+class _CompileEndpoint:
+ base_url: str
+ gateway_token: str
+ http_timeout_seconds: float
+ poll_interval_ms: int
+ local: bool = False
+
+
+class CompileAPIClient:
+ """Client for submitting Compile tasks through the Runtime API."""
+
+ def __init__(self, endpoint: _CompileEndpoint) -> None:
+ self._endpoint = endpoint
+
+ def _headers(
+ self,
+ connection: Mapping[str, Any],
+ *,
+ idempotency_key: str | None = None,
+ ) -> dict[str, str]:
+ headers = {
+ "Content-Type": "application/json",
+ }
+ if self._endpoint.gateway_token:
+ headers["X-Gateway-Token"] = self._endpoint.gateway_token
+ api_key = str(connection.get("api_key") or "").strip()
+ if api_key:
+ headers["X-API-Key"] = api_key
+ if idempotency_key:
+ headers["Idempotency-Key"] = idempotency_key
+ return headers
+
+ async def create(
+ self,
+ payload: Mapping[str, Any],
+ *,
+ connection: Mapping[str, Any],
+ idempotency_key: str,
+ ) -> CompileSessionAccepted:
+ response = await self._request(
+ "POST",
+ "/runtime/v1/tasks",
+ json=payload,
+ headers=self._headers(connection, idempotency_key=idempotency_key),
+ )
+ return self._validate(CompileSessionAccepted, response)
+
+ async def get(
+ self,
+ session_id: str,
+ *,
+ connection: Mapping[str, Any],
+ ) -> CompileSessionStatus:
+ body = await self._request(
+ "POST",
+ "/runtime/v1/tasks/status",
+ json={"session_id": session_id},
+ headers=self._headers(connection),
+ )
+ return self._validate(CompileSessionStatus, body)
+
+ async def cancel(
+ self,
+ session_id: str,
+ *,
+ connection: Mapping[str, Any],
+ ) -> CompileSessionStatus:
+ body = await self._request(
+ "POST",
+ "/runtime/v1/tasks/cancel",
+ json={"session_id": session_id},
+ headers=self._headers(connection),
+ )
+ return self._validate(CompileSessionStatus, body)
+
+ async def _request(
+ self,
+ method: str,
+ path: str,
+ *,
+ headers: Mapping[str, str],
+ json: Mapping[str, Any],
+ ) -> Any:
+ try:
+ async with httpx.AsyncClient(
+ timeout=self._endpoint.http_timeout_seconds,
+ trust_env=not self._endpoint.local,
+ follow_redirects=False,
+ ) as client:
+ response = await client.request(
+ method,
+ f"{self._endpoint.base_url}{path}",
+ headers=dict(headers),
+ json=dict(json),
+ )
+ except httpx.RequestError as exc:
+ raise ExternalTaskError("UNAVAILABLE", str(exc), transient=True) from exc
+
+ try:
+ body = response.json()
+ except ValueError as exc:
+ if not response.is_success:
+ raise ExternalTaskError(
+ "UNAVAILABLE" if response.status_code >= 500 else "INVALID_ARGUMENT",
+ "Compile API request failed",
+ transient=response.status_code in {408, 425, 429}
+ or response.status_code >= 500,
+ ) from exc
+ raise ExternalTaskError(
+ "INVALID_RESPONSE",
+ "Compile API returned a non-JSON response",
+ transient=False,
+ ) from exc
+ if response.is_success:
+ return body
+
+ detail = body.get("detail") if isinstance(body, dict) else None
+ error = body.get("error") if isinstance(body, dict) else None
+ source = detail if isinstance(detail, dict) else error if isinstance(error, dict) else {}
+ default_code = "UNAVAILABLE" if response.status_code >= 500 else "INVALID_ARGUMENT"
+ code = str(source.get("code") or default_code)
+ message = str(source.get("message") or detail or error or "Compile API request failed")
+ raise ExternalTaskError(
+ code,
+ message,
+ transient=response.status_code in {408, 425, 429} or response.status_code >= 500,
+ )
+
+ @staticmethod
+ def _validate(model: type[BaseModel], body: Any) -> Any:
+ try:
+ return model.model_validate(body)
+ except ValidationError as exc:
+ raise ExternalTaskError(
+ "INVALID_RESPONSE",
+ f"Compile API returned an invalid response: {exc}",
+ transient=False,
+ ) from exc
+
+
+class CompileService:
+ """Validate Compile requests and own their external task lifecycle."""
+
+ task_type = "compile"
+ task_id_prefix = "cmp_"
+ poll_max_attempts = 3
+
+ def __init__(
+ self,
+ config: CompileApiConfig,
+ tasks: ExternalTaskService,
+ fs: FSService,
+ ) -> None:
+ self._config = config
+ self._tasks = tasks
+ self._fs = fs
+ self._local_endpoint: _CompileEndpoint | None = None
+
+ @property
+ def poll_interval_seconds(self) -> float:
+ return self._endpoint().poll_interval_ms / 1000.0
+
+ def configure_local_backend(self, base_url: str, gateway_token: str) -> None:
+ if self._config.base_url:
+ return
+ self._local_endpoint = _CompileEndpoint(
+ base_url=base_url.rstrip("/"),
+ gateway_token=gateway_token,
+ http_timeout_seconds=10.0,
+ poll_interval_ms=30000,
+ local=True,
+ )
+
+ def _endpoint(self) -> _CompileEndpoint:
+ if self._config.base_url:
+ return _CompileEndpoint(
+ base_url=self._config.base_url,
+ gateway_token=self._config.gateway_token,
+ http_timeout_seconds=self._config.http_timeout_seconds,
+ poll_interval_ms=self._config.poll_interval_ms,
+ )
+ if self._local_endpoint is not None:
+ return self._local_endpoint
+ raise UnavailableError("compile API", "compile_api.base_url is not configured")
+
+ def _client(self) -> CompileAPIClient:
+ return CompileAPIClient(self._endpoint())
+
+ async def create(
+ self,
+ request: CompileRequest,
+ *,
+ connection: Mapping[str, Any],
+ ctx: RequestContext,
+ ) -> TaskRecord:
+ endpoint = self._endpoint()
+ if not endpoint.local and not str(connection.get("api_key") or "").strip():
+ raise UnauthenticatedError("Compile requires a forwardable OpenViking API key")
+ normalized = await self._normalize_request(request, ctx)
+ payload, private_payload = self._split_payload(normalized)
+ return await self._tasks.create(
+ self.task_type,
+ resource_id=", ".join(normalized.from_),
+ payload=payload,
+ private_payload=private_payload,
+ connection=connection,
+ ctx=ctx,
+ )
+
+ async def submit(
+ self,
+ ov_task_id: str,
+ payload: Mapping[str, Any],
+ private_payload: Mapping[str, Any],
+ connection: Mapping[str, Any],
+ ) -> str:
+ request_payload = dict(payload)
+ public_args = request_payload.get("args")
+ private_args = private_payload.get("args")
+ if isinstance(public_args, dict) or isinstance(private_args, dict):
+ request_payload["args"] = {
+ **(public_args if isinstance(public_args, dict) else {}),
+ **(private_args if isinstance(private_args, dict) else {}),
+ }
+ accepted = await self._client().create(
+ {"task_type": self.task_type, "payload": request_payload},
+ connection=connection,
+ idempotency_key=ov_task_id,
+ )
+ return accepted.session_id
+
+ async def get(
+ self,
+ external_task_id: str,
+ connection: Mapping[str, Any],
+ ) -> ExternalTaskSnapshot:
+ return self._snapshot(await self._client().get(external_task_id, connection=connection))
+
+ async def cancel(
+ self,
+ external_task_id: str,
+ connection: Mapping[str, Any],
+ ) -> ExternalTaskSnapshot:
+ return self._snapshot(await self._client().cancel(external_task_id, connection=connection))
+
+ async def _normalize_request(
+ self,
+ request: CompileRequest,
+ ctx: RequestContext,
+ ) -> CompileRequest:
+ sources: list[str] = []
+ for index, source in enumerate(request.from_):
+ uri = validate_request_viking_uri(
+ resolve_path_variables(source),
+ ctx,
+ field_name=f"from[{index}]",
+ ).rstrip("/")
+ stat = await self._fs.stat(uri, ctx)
+ if not stat.get("isDir"):
+ raise InvalidArgumentError(f"Compile source must be a directory: {uri}")
+ canonical = str(stat.get("uri") or uri).rstrip("/")
+ if canonical not in sources:
+ sources.append(canonical)
+
+ skill = request.skill
+ if skill.endswith("/SKILL.md"):
+ skill = skill[: -len("/SKILL.md")]
+ skill = validate_request_viking_uri(
+ resolve_path_variables(skill),
+ ctx,
+ field_name="skill",
+ ).rstrip("/")
+ if not classify_uri(skill).is_skill_root:
+ raise InvalidArgumentError("skill must resolve to a Skill directory or SKILL.md")
+ skill_stat = await self._fs.stat(skill, ctx)
+ if not skill_stat.get("isDir"):
+ raise InvalidArgumentError("skill must resolve to a Skill directory or SKILL.md")
+ skill = str(skill_stat.get("uri") or skill).rstrip("/")
+ skill_file = await self._fs.stat(f"{skill}/SKILL.md", ctx)
+ if skill_file.get("isDir"):
+ raise InvalidArgumentError("Skill directory must contain a SKILL.md file")
+
+ target = validate_request_viking_uri(
+ resolve_path_variables(request.to),
+ ctx,
+ field_name="to",
+ ).rstrip("/")
+ self._validate_target(target)
+ await self._fs.ensure_write_access(target, ctx)
+ try:
+ target_stat = await self._fs.stat(target, ctx)
+ except NotFoundError:
+ pass
+ else:
+ if not target_stat.get("isDir"):
+ raise InvalidArgumentError("Compile target must be a directory")
+ target = str(target_stat.get("uri") or target).rstrip("/")
+
+ return request.model_copy(
+ update={"from_": sources, "to": target, "skill": skill},
+ )
+
+ @staticmethod
+ def _validate_target(target: str) -> None:
+ classification = classify_uri(target)
+ parts = uri_parts(target)
+ if classification.context_type == "skill":
+ if not classification.is_skill_namespace or (
+ classification.scope == "agent" and parts != ["agent", "skills"]
+ ):
+ raise InvalidArgumentError(
+ "Compile Skill target must be a supported skills namespace"
+ )
+ return
+ if classification.context_type not in {"resource", "memory"}:
+ raise InvalidArgumentError(
+ "Compile target must be a resource, memory, or skills directory"
+ )
+ if classification.context_type == "memory":
+ if (
+ classification.content_index is None
+ or len(parts) <= classification.content_index + 1
+ ):
+ raise InvalidArgumentError("Compile target must be inside a memory type directory")
+ elif parts == ["resources"] or (
+ classification.content_index is not None
+ and len(parts) <= classification.content_index + 1
+ ):
+ raise InvalidArgumentError("Compile target must be inside a resource directory")
+
+ @staticmethod
+ def _split_payload(request: CompileRequest) -> tuple[dict[str, Any], dict[str, Any]]:
+ payload = request.model_dump(mode="json", by_alias=True, exclude_none=True)
+ args = payload.get("args")
+ if not isinstance(args, dict) or "user_key" not in args:
+ return payload, {}
+ private_payload = {"args": {"user_key": args.pop("user_key")}}
+ if not args:
+ payload.pop("args", None)
+ return payload, private_payload
+
+ @staticmethod
+ def _snapshot(task: CompileSessionStatus) -> ExternalTaskSnapshot:
+ status = (task.status or "").strip().lower()
+ if not status:
+ normalized_stage = task.stage.strip().lower().replace(" ", "")
+ if "cancelled" in normalized_stage or "canceled" in normalized_stage:
+ status = "cancelled"
+ elif task.error is not None or any(
+ marker in normalized_stage for marker in ("failed", "error")
+ ):
+ status = "failed"
+ elif any(
+ marker in normalized_stage
+ for marker in ("completed", "succeeded", "success", "finished")
+ ):
+ status = "completed"
+ else:
+ status = "running"
+ if status in _ACTIVE_STATUSES:
+ status = "running"
+ elif status == "cancelling":
+ pass
+ elif status not in _TERMINAL_STATUSES:
+ raise ExternalTaskError(
+ "INVALID_RESPONSE",
+ f"Unknown Compile task status: {status}",
+ transient=False,
+ )
+
+ if isinstance(task.error, CompileErrorInfo):
+ error_code = task.error.code
+ error_message = task.error.message
+ elif task.error:
+ error_code = "UNKNOWN"
+ error_message = str(task.error)
+ else:
+ error_code = None
+ error_message = None
+ return ExternalTaskSnapshot(
+ status=status,
+ stage=task.stage,
+ result=task.result,
+ meta=task.meta,
+ error_code=error_code,
+ error_message=error_message,
+ )
+
+__all__ = [
+ "CompileAPIClient",
+ "CompileRequest",
+ "CompileService",
+ "CompileSessionAccepted",
+ "CompileSessionStatus",
+]
diff --git a/openviking/service/core.py b/openviking/service/core.py
index 51bc2ed06..e1a1deac3 100644
--- a/openviking/service/core.py
+++ b/openviking/service/core.py
@@ -20,7 +20,9 @@ from openviking.server.account_settings import (
)
from openviking.server.identity import RequestContext, Role
from openviking.service.agent_evolution_service import AgentEvolutionService
+from openviking.service.compile_service import CompileService
from openviking.service.debug_service import DebugService
+from openviking.service.external_task_service import ExternalTaskService
from openviking.service.fs_service import FSService
from openviking.service.mineru_preflight import wait_for_mineru_ready
from openviking.service.pack_service import PackService
@@ -35,6 +37,7 @@ from openviking.storage.acl import AclManager
from openviking.storage.collection_schemas import init_context_collection
from openviking.storage.index_consistency import check_index_consistency
from openviking.storage.queuefs.add_resource_processor import AddResourceProcessor
+from openviking.storage.queuefs.external_task_processor import ExternalTaskProcessor
from openviking.storage.queuefs.queue_manager import QueueManager, init_queue_manager
from openviking.storage.queuefs.session_commit_processor import SessionCommitProcessor
from openviking.storage.viking_fs import VikingFS, init_viking_fs
@@ -115,6 +118,13 @@ class OpenVikingService:
self._session_service = SessionService()
self._debug_service = DebugService()
self._agent_evolution_service = AgentEvolutionService()
+ self._external_task_service = ExternalTaskService()
+ self._compile_service = CompileService(
+ config.compile_api,
+ self._external_task_service,
+ self._fs_service,
+ )
+ self._external_task_service.register(self._compile_service)
# State
self._initialized = False
@@ -136,6 +146,7 @@ class OpenVikingService:
max_concurrent_external_parse=config.queue_workers.external_parse.max_concurrent,
max_concurrent_add_resource=config.queue_workers.add_resource.max_concurrent,
max_concurrent_session_commit=config.queue_workers.session_commit.max_concurrent,
+ max_concurrent_external_task=config.queue_workers.external_task.max_concurrent,
binding_config=binding_config,
git_config=config.git,
)
@@ -154,6 +165,7 @@ class OpenVikingService:
max_concurrent_external_parse: int = 4,
max_concurrent_add_resource: int = 4,
max_concurrent_session_commit: int = 8,
+ max_concurrent_external_task: int = 10,
binding_config: Any = None,
*,
git_config: Optional[GitConfig] = None,
@@ -177,6 +189,7 @@ class OpenVikingService:
max_concurrent_external_parse=max_concurrent_external_parse,
max_concurrent_add_resource=max_concurrent_add_resource,
max_concurrent_session_commit=max_concurrent_session_commit,
+ max_concurrent_external_task=max_concurrent_external_task,
)
else:
logger.warning("RAGFS client not initialized, skipping queue manager")
@@ -310,6 +323,11 @@ class OpenVikingService:
"""Get Agent Evolution query service."""
return self._agent_evolution_service
+ @property
+ def compile(self) -> CompileService:
+ """Get the Compile task service."""
+ return self._compile_service
+
async def initialize(self) -> None:
"""Initialize OpenViking storage and indexes."""
if self._initialized:
@@ -332,6 +350,9 @@ class OpenVikingService:
max_concurrent_session_commit=(
self._config.queue_workers.session_commit.max_concurrent
),
+ max_concurrent_external_task=(
+ self._config.queue_workers.external_task.max_concurrent
+ ),
binding_config=self._build_ragfs_binding_config(),
git_config=self._config.git,
)
@@ -490,6 +511,14 @@ class OpenVikingService:
),
allow_create=True,
)
+ self._queue_manager.get_queue(
+ self._queue_manager.EXTERNAL_TASK,
+ dequeue_handler=ExternalTaskProcessor(
+ self._external_task_service,
+ asyncio.get_running_loop(),
+ ),
+ allow_create=True,
+ )
# Auth state is initialized by the HTTP server after the core service.
# Register the durable queue now so task tracking can rebuild its work;
# the user-deletion service binds the handler once auth is ready.
diff --git a/openviking/service/external_task_service.py b/openviking/service/external_task_service.py
new file mode 100644
index 000000000..c1689e05e
--- /dev/null
+++ b/openviking/service/external_task_service.py
@@ -0,0 +1,448 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""Durable execution of asynchronous tasks owned by external services."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from typing import Any, Awaitable, Callable, Mapping, Protocol
+from uuid import uuid4
+
+from openviking.server.identity import RequestContext
+from openviking.service.task_tracker import TaskRecord, TaskStatus, get_task_tracker
+from openviking.service.task_tracker_concurrency import run_to_completion
+from openviking.storage.queuefs import QueueManager, get_queue_manager
+from openviking_cli.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+_ACTIVE_STATUSES = frozenset({"pending", "running", "cancelling"})
+
+
+class ExternalTaskError(RuntimeError):
+ """A classified provider failure used by the durable retry loop."""
+
+ def __init__(self, code: str, message: str, *, transient: bool) -> None:
+ super().__init__(message)
+ self.code = code
+ self.transient = transient
+
+
+@dataclass(frozen=True)
+class ExternalTaskSnapshot:
+ """Provider-independent state returned by an external task API."""
+
+ status: str
+ stage: str | None = None
+ result: dict[str, Any] | None = None
+ meta: dict[str, Any] | None = None
+ error_code: str | None = None
+ error_message: str | None = None
+
+
+class ExternalTaskProvider(Protocol):
+ """Adapter contract for one external asynchronous task type."""
+
+ task_type: str
+ task_id_prefix: str
+ poll_max_attempts: int
+
+ @property
+ def poll_interval_seconds(self) -> float: ...
+
+ async def submit(
+ self,
+ ov_task_id: str,
+ payload: Mapping[str, Any],
+ private_payload: Mapping[str, Any],
+ connection: Mapping[str, Any],
+ ) -> str: ...
+
+ async def get(
+ self,
+ external_task_id: str,
+ connection: Mapping[str, Any],
+ ) -> ExternalTaskSnapshot: ...
+
+ async def cancel(
+ self,
+ external_task_id: str,
+ connection: Mapping[str, Any],
+ ) -> ExternalTaskSnapshot: ...
+
+
+class ExternalTaskService:
+ """Own OV task state while registered providers perform the actual work."""
+
+ def __init__(self) -> None:
+ self._providers: dict[str, ExternalTaskProvider] = {}
+
+ def register(self, provider: ExternalTaskProvider) -> None:
+ if provider.task_type in self._providers:
+ raise ValueError(f"External task provider already registered: {provider.task_type}")
+ self._providers[provider.task_type] = provider
+
+ def _provider(self, task_type: str) -> ExternalTaskProvider:
+ provider = self._providers.get(task_type)
+ if provider is None:
+ raise ExternalTaskError(
+ "UNAVAILABLE",
+ f"External task provider is not registered: {task_type}",
+ transient=False,
+ )
+ return provider
+
+ async def create(
+ self,
+ task_type: str,
+ *,
+ resource_id: str | None,
+ payload: Mapping[str, Any],
+ private_payload: Mapping[str, Any] | None = None,
+ connection: Mapping[str, Any],
+ ctx: RequestContext,
+ ) -> TaskRecord:
+ provider = self._provider(task_type)
+ tracker = get_task_tracker()
+ task = await tracker.create(
+ task_type,
+ resource_id=resource_id,
+ account_id=ctx.account_id,
+ user_id=ctx.user.user_id,
+ task_id=f"{provider.task_id_prefix}{uuid4().hex}",
+ meta={"request": dict(payload)},
+ auth={
+ "openviking_connection": dict(connection),
+ "external_request_private": dict(private_payload or {}),
+ },
+ )
+ enqueued = False
+ try:
+ await get_queue_manager().enqueue(
+ QueueManager.EXTERNAL_TASK,
+ {
+ "task_id": task.task_id,
+ "account_id": ctx.account_id,
+ "user_id": ctx.user.user_id,
+ },
+ )
+ enqueued = True
+ await tracker.update_stage(
+ task.task_id,
+ "queued",
+ account_id=ctx.account_id,
+ user_id=ctx.user.user_id,
+ )
+ current = await tracker.get(
+ task.task_id,
+ account_id=ctx.account_id,
+ user_id=ctx.user.user_id,
+ )
+ if current is not None:
+ task = current
+ except BaseException:
+ if not enqueued:
+ await tracker.fail(
+ task.task_id,
+ "Failed to enqueue external task",
+ account_id=ctx.account_id,
+ user_id=ctx.user.user_id,
+ )
+ raise
+ return task
+
+ async def execute(self, task_id: str, account_id: str, user_id: str) -> None:
+ tracker = get_task_tracker()
+ task = await tracker.get(task_id, account_id=account_id, user_id=user_id)
+ if task is None or task.status in {
+ TaskStatus.COMPLETED,
+ TaskStatus.FAILED,
+ TaskStatus.CANCELLED,
+ }:
+ return
+ # The outcome is persisted before QueueFS ACK removes the owned work.
+ # After a crash in that window, let the recovered delivery ACK without
+ # resubmitting credentials that have already been cleared.
+ if task.result is not None or task.error is not None:
+ return
+
+ provider = self._provider(task.task_type)
+ payload = task.meta.get("request")
+ if not isinstance(payload, dict):
+ await tracker.fail(
+ task_id,
+ "INVALID_ARGUMENT: External task request is missing",
+ account_id=account_id,
+ user_id=user_id,
+ )
+ return
+ auth = await self._task_auth(task_id, account_id, user_id)
+ connection = self._mapping(auth.get("openviking_connection"))
+ private_payload = self._mapping(auth.get("external_request_private"))
+ external_task_id = str(auth.get("external_task_id") or "").strip() or None
+ try:
+ await tracker.start(
+ task_id,
+ account_id=account_id,
+ user_id=user_id,
+ stage="polling" if external_task_id else "submitting",
+ )
+ if external_task_id is None:
+ external_task_id = await self._retry(
+ lambda: provider.submit(task_id, payload, private_payload, connection),
+ task_id=task_id,
+ operation_name="submit",
+ poll_interval=provider.poll_interval_seconds,
+ max_attempts=provider.poll_max_attempts,
+ )
+ await tracker.update_task_auth(
+ task_id,
+ {"external_task_id": external_task_id},
+ account_id=account_id,
+ user_id=user_id,
+ )
+ while True:
+ snapshot = await self._retry(
+ lambda: provider.get(external_task_id, connection),
+ task_id=task_id,
+ operation_name="poll",
+ poll_interval=provider.poll_interval_seconds,
+ max_attempts=provider.poll_max_attempts,
+ )
+ if await self._apply_snapshot(
+ snapshot,
+ task_id=task_id,
+ account_id=account_id,
+ user_id=user_id,
+ ):
+ return
+ await asyncio.sleep(provider.poll_interval_seconds)
+ except ExternalTaskError as exc:
+ await tracker.fail(
+ task_id,
+ self._format_error(exc.code, str(exc)),
+ account_id=account_id,
+ user_id=user_id,
+ )
+ except asyncio.CancelledError:
+ if not tracker.is_cancellation_requested(task_id):
+ raise
+ await run_to_completion(
+ lambda: self._cancel_external(
+ provider,
+ ov_task_id=task_id,
+ payload=payload,
+ private_payload=private_payload,
+ connection=connection,
+ external_task_id=external_task_id,
+ account_id=account_id,
+ user_id=user_id,
+ )
+ )
+ raise
+
+ async def cancel_recovered(self, task_id: str, account_id: str, user_id: str) -> None:
+ tracker = get_task_tracker()
+ task = await tracker.get(task_id, account_id=account_id, user_id=user_id)
+ if task is None or task.stage in {None, "queued"}:
+ return
+ payload = task.meta.get("request")
+ if not isinstance(payload, dict):
+ raise ExternalTaskError(
+ "INVALID_ARGUMENT",
+ "External task request is missing",
+ transient=False,
+ )
+ auth = await self._task_auth(task_id, account_id, user_id)
+ await self._cancel_external(
+ self._provider(task.task_type),
+ ov_task_id=task_id,
+ payload=payload,
+ private_payload=self._mapping(auth.get("external_request_private")),
+ connection=self._mapping(auth.get("openviking_connection")),
+ external_task_id=str(auth.get("external_task_id") or "").strip() or None,
+ account_id=account_id,
+ user_id=user_id,
+ )
+
+ @staticmethod
+ async def _task_auth(task_id: str, account_id: str, user_id: str) -> dict[str, Any]:
+ return await get_task_tracker().get_task_auth(
+ task_id,
+ account_id=account_id,
+ user_id=user_id,
+ )
+
+ @staticmethod
+ def _mapping(value: Any) -> dict[str, Any]:
+ return dict(value) if isinstance(value, dict) else {}
+
+ async def _apply_snapshot(
+ self,
+ snapshot: ExternalTaskSnapshot,
+ *,
+ task_id: str,
+ account_id: str,
+ user_id: str,
+ ) -> bool:
+ tracker = get_task_tracker()
+ if snapshot.stage is not None or snapshot.meta:
+ task = await tracker.get(
+ task_id,
+ account_id=account_id,
+ user_id=user_id,
+ )
+ stage = snapshot.stage or snapshot.status
+ meta = snapshot.meta or {}
+ if task is not None and (
+ task.stage != stage
+ or any(key not in task.meta or task.meta[key] != value for key, value in meta.items())
+ ):
+ await tracker.update_stage(
+ task_id,
+ stage,
+ account_id=account_id,
+ user_id=user_id,
+ meta=meta,
+ )
+ if snapshot.status in _ACTIVE_STATUSES:
+ return False
+ if snapshot.status == "completed":
+ await tracker.complete(
+ task_id,
+ snapshot.result or snapshot.meta or {},
+ account_id=account_id,
+ user_id=user_id,
+ )
+ return True
+ if snapshot.status == "failed":
+ await tracker.fail(
+ task_id,
+ self._format_error(
+ snapshot.error_code or "UNKNOWN",
+ snapshot.error_message or "External task failed",
+ ),
+ account_id=account_id,
+ user_id=user_id,
+ )
+ return True
+ if snapshot.status == "cancelled":
+ await tracker.record_cancelled(
+ task_id,
+ account_id=account_id,
+ user_id=user_id,
+ )
+ return True
+ raise ExternalTaskError(
+ "INVALID_RESPONSE",
+ f"Unknown external task status: {snapshot.status}",
+ transient=False,
+ )
+
+ async def _cancel_external(
+ self,
+ provider: ExternalTaskProvider,
+ *,
+ ov_task_id: str,
+ payload: Mapping[str, Any],
+ private_payload: Mapping[str, Any],
+ connection: Mapping[str, Any],
+ external_task_id: str | None,
+ account_id: str,
+ user_id: str,
+ ) -> None:
+ max_attempts = provider.poll_max_attempts
+ # Returning allows QueueFS to ACK the work and finalize cancellation.
+ # Keep ownership until the provider confirms a terminal state.
+ while True:
+ try:
+ if external_task_id is None:
+ # Submission may have reached the provider before local cancellation
+ # interrupted its response. Recover it with the same idempotency key.
+ external_task_id = await self._retry(
+ lambda: provider.submit(ov_task_id, payload, private_payload, connection),
+ task_id=ov_task_id,
+ operation_name="recover before cancel",
+ poll_interval=provider.poll_interval_seconds,
+ max_attempts=max_attempts,
+ )
+ await get_task_tracker().update_task_auth(
+ ov_task_id,
+ {"external_task_id": external_task_id},
+ account_id=account_id,
+ user_id=user_id,
+ )
+ snapshot = await self._retry(
+ lambda task_id=external_task_id: provider.cancel(task_id, connection),
+ task_id=ov_task_id,
+ operation_name="cancel",
+ poll_interval=provider.poll_interval_seconds,
+ max_attempts=max_attempts,
+ )
+ while True:
+ if await self._apply_snapshot(
+ snapshot,
+ task_id=ov_task_id,
+ account_id=account_id,
+ user_id=user_id,
+ ):
+ return
+ await asyncio.sleep(provider.poll_interval_seconds)
+ snapshot = await self._retry(
+ lambda task_id=external_task_id: provider.get(task_id, connection),
+ task_id=ov_task_id,
+ operation_name="poll cancellation",
+ poll_interval=provider.poll_interval_seconds,
+ max_attempts=max_attempts,
+ )
+ except ExternalTaskError as exc:
+ logger.warning(
+ "External task cancellation will retry task=%s code=%s: %s",
+ ov_task_id,
+ exc.code,
+ exc,
+ )
+ await asyncio.sleep(provider.poll_interval_seconds)
+
+ @staticmethod
+ async def _retry(
+ action: Callable[[], Awaitable[Any]],
+ *,
+ task_id: str,
+ operation_name: str,
+ poll_interval: float,
+ max_attempts: int,
+ ) -> Any:
+ delay = max(poll_interval, 0.2)
+ attempts = 0
+ while True:
+ try:
+ return await action()
+ except ExternalTaskError as exc:
+ if not exc.transient:
+ raise
+ attempts += 1
+ if attempts >= max_attempts:
+ raise
+ logger.warning(
+ "External task %s will retry task=%s code=%s: %s",
+ operation_name,
+ task_id,
+ exc.code,
+ exc,
+ )
+ await asyncio.sleep(delay)
+ delay = min(delay * 2, 30.0)
+
+ @staticmethod
+ def _format_error(code: str, message: str) -> str:
+ return f"{code}: {message}"
+
+
+__all__ = [
+ "ExternalTaskError",
+ "ExternalTaskProvider",
+ "ExternalTaskService",
+ "ExternalTaskSnapshot",
+]
diff --git a/openviking/service/fs_service.py b/openviking/service/fs_service.py
index 6310a933f..2ff514739 100644
--- a/openviking/service/fs_service.py
+++ b/openviking/service/fs_service.py
@@ -27,7 +27,7 @@ from openviking.storage.abstract_overview import (
plan_abstract_overview_refresh,
render_abstract_overview,
)
-from openviking.storage.acl import CreatorAclGrant
+from openviking.storage.acl import AclAction, CreatorAclGrant
from openviking.storage.content_write import ContentWriteCoordinator
from openviking.storage.expr import And, Eq, In, Or
from openviking.storage.queuefs import SemanticMsg, get_queue_manager
@@ -933,6 +933,11 @@ class FSService:
viking_fs = self._ensure_initialized()
return await viking_fs.stat(uri, ctx=ctx, skip_count=skip_count)
+ async def ensure_write_access(self, uri: str, ctx: RequestContext) -> None:
+ """Validate write access without mutating the target."""
+ viking_fs = self._ensure_initialized()
+ await viking_fs._ensure_access(uri, ctx, action=AclAction.WRITE)
+
async def system_sync_status(self, uri: str, ctx: RequestContext) -> Dict[str, Any]:
"""Return multi-write sync status for one Viking URI subtree."""
viking_fs = self._ensure_initialized()
diff --git a/openviking/service/task_tracker.py b/openviking/service/task_tracker.py
index 5c8ae5140..6ca78af30 100644
--- a/openviking/service/task_tracker.py
+++ b/openviking/service/task_tracker.py
@@ -58,6 +58,7 @@ _ACTIVE_STATUSES = (TaskStatus.PENDING, TaskStatus.RUNNING, TaskStatus.CANCELLIN
_CANCELLABLE_TASK_TYPES = {
"add_resource",
+ "compile",
"session_commit",
"admin_reindex",
"snapshot_restore_reindex",
@@ -495,10 +496,12 @@ class TaskTracker:
stage: str,
account_id: Optional[str] = None,
user_id: Optional[str] = None,
+ *,
+ meta: Optional[Dict[str, Any]] = None,
) -> None:
- """Update task stage without changing its lifecycle status."""
+ """Update task progress without changing its lifecycle status."""
await self._dispatcher.run(
- lambda: self._update_stage_on_owner(task_id, stage, account_id, user_id)
+ lambda: self._update_stage_on_owner(task_id, stage, account_id, user_id, meta)
)
async def _update_stage_on_owner(
@@ -507,12 +510,49 @@ class TaskTracker:
stage: str,
account_id: Optional[str],
user_id: Optional[str],
+ meta: Optional[Dict[str, Any]],
) -> None:
async with self._task_locks.acquire(task_id):
task = await self._load_for_update(task_id, account_id, user_id)
- if task and task.status in (TaskStatus.PENDING, TaskStatus.RUNNING):
+ if task and task.status in _ACTIVE_STATUSES:
updated = deepcopy(task)
updated.stage = stage
+ if meta:
+ updated.meta.update(deepcopy(meta))
+ updated.updated_at = self._next_updated_at(task)
+ await self._persist_and_publish("update", updated)
+
+ async def update_task_auth(
+ self,
+ task_id: str,
+ values: Dict[str, Any],
+ *,
+ account_id: str,
+ user_id: str,
+ ) -> None:
+ """Persist private state required to resume an active task."""
+ self._validate_owner(account_id, user_id)
+ await self._dispatcher.run(
+ lambda: self._update_task_auth_on_owner(
+ task_id,
+ values,
+ account_id,
+ user_id,
+ )
+ )
+
+ async def _update_task_auth_on_owner(
+ self,
+ task_id: str,
+ values: Dict[str, Any],
+ account_id: str,
+ user_id: str,
+ ) -> None:
+ async with self._task_locks.acquire(task_id):
+ task = await self._load_for_update(task_id, account_id, user_id)
+ if task and task.status in _ACTIVE_STATUSES:
+ updated = deepcopy(task)
+ updated.auth.update(deepcopy(values))
updated.updated_at = self._next_updated_at(task)
await self._persist_and_publish("update", updated)
@@ -566,6 +606,32 @@ class TaskTracker:
terminal_status=TaskStatus.CANCELLED,
)
+ async def record_cancelled(
+ self,
+ task_id: str,
+ account_id: Optional[str] = None,
+ user_id: Optional[str] = None,
+ ) -> None:
+ """Record cancellation reported by the task owner without cancelling its worker."""
+ await self._dispatcher.run(
+ lambda: self._record_cancelled_on_owner(task_id, account_id, user_id)
+ )
+
+ async def _record_cancelled_on_owner(
+ self,
+ task_id: str,
+ account_id: Optional[str],
+ user_id: Optional[str],
+ ) -> None:
+ async with self._task_locks.acquire(task_id):
+ task = await self._load_for_update(task_id, account_id, user_id)
+ if task and task.status in _ACTIVE_STATUSES:
+ updated = deepcopy(task)
+ updated.status = TaskStatus.CANCELLING
+ updated.updated_at = self._next_updated_at(task)
+ await self._persist_and_publish("update", updated)
+ await self._finalize_task_on_owner(task_id, account_id, user_id)
+
async def _record_outcome(
self,
task_id: str,
diff --git a/openviking/storage/queuefs/external_task_processor.py b/openviking/storage/queuefs/external_task_processor.py
new file mode 100644
index 000000000..fc4031fea
--- /dev/null
+++ b/openviking/storage/queuefs/external_task_processor.py
@@ -0,0 +1,74 @@
+# Copyright (c) 2026 Beijing Volcano Engine Technology Co., Ltd.
+# SPDX-License-Identifier: AGPL-3.0
+"""QueueFS consumer for externally executed tasks."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from typing import Any, Callable, Coroutine, Dict, Optional
+
+from openviking.service.external_task_service import ExternalTaskService
+from openviking.service.task_tracker_concurrency import OwnerLoopDispatcher
+from openviking.storage.queuefs.named_queue import DequeueHandlerBase
+
+
+class ExternalTaskProcessor(DequeueHandlerBase):
+ def __init__(
+ self,
+ service: ExternalTaskService,
+ service_loop: asyncio.AbstractEventLoop,
+ ) -> None:
+ self._service = service
+ self._dispatcher = OwnerLoopDispatcher()
+ if self._dispatcher.bind_current_loop() is not service_loop:
+ raise ValueError("ExternalTaskProcessor must be created on the service event loop")
+
+ @staticmethod
+ def _parse(data: Dict[str, Any]) -> tuple[str, str, str]:
+ payload = data.get("data", data)
+ if isinstance(payload, str):
+ payload = json.loads(payload)
+ if not isinstance(payload, dict):
+ raise ValueError("External task queue payload must be an object")
+ task_id = str(payload.get("task_id") or "")
+ account_id = str(payload.get("account_id") or "")
+ user_id = str(payload.get("user_id") or "")
+ if not task_id or not account_id or not user_id:
+ raise ValueError("External task queue payload is missing task ownership")
+ return task_id, account_id, user_id
+
+ async def _run_on_service_loop(
+ self,
+ factory: Callable[[], Coroutine[Any, Any, None]],
+ ) -> None:
+ await self._dispatcher.run(factory)
+
+ async def on_dequeue(self, data: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+ if not data:
+ return None
+ try:
+ task_id, account_id, user_id = self._parse(data)
+ except (json.JSONDecodeError, TypeError, ValueError) as exc:
+ self.report_error(str(exc), data)
+ return None
+ await self._run_on_service_loop(lambda: self._service.execute(task_id, account_id, user_id))
+ self.report_success()
+ return None
+
+ async def on_cancelled(self, data: Optional[Dict[str, Any]]) -> Optional[Dict[str, Any]]:
+ if not data:
+ return None
+ try:
+ task_id, account_id, user_id = self._parse(data)
+ except (json.JSONDecodeError, TypeError, ValueError) as exc:
+ self.report_error(str(exc), data)
+ return None
+ await self._run_on_service_loop(
+ lambda: self._service.cancel_recovered(task_id, account_id, user_id)
+ )
+ self.report_success()
+ return None
+
+
+__all__ = ["ExternalTaskProcessor"]
diff --git a/openviking/storage/queuefs/queue_manager.py b/openviking/storage/queuefs/queue_manager.py
index fd327183d..bf7e3e430 100644
--- a/openviking/storage/queuefs/queue_manager.py
+++ b/openviking/storage/queuefs/queue_manager.py
@@ -36,6 +36,7 @@ def init_queue_manager(
max_concurrent_external_parse: int = 4,
max_concurrent_add_resource: int = 4,
max_concurrent_session_commit: int = DEFAULT_MAX_CONCURRENT_SESSION_COMMIT,
+ max_concurrent_external_task: int = 10,
) -> "QueueManager":
"""Initialize QueueManager singleton.
@@ -59,6 +60,7 @@ def init_queue_manager(
max_concurrent_external_parse=max_concurrent_external_parse,
max_concurrent_add_resource=max_concurrent_add_resource,
max_concurrent_session_commit=max_concurrent_session_commit,
+ max_concurrent_external_task=max_concurrent_external_task,
)
return _instance
@@ -83,6 +85,7 @@ class QueueManager:
EXTERNAL_PARSE = "ExternalParse"
ADD_RESOURCE = "AddResource"
SESSION_COMMIT = "SessionCommit"
+ EXTERNAL_TASK = "ExternalTask"
USER_DELETION = "UserDeletion"
# A deferred archive re-enqueues itself; throttle the next scheduling round.
_SESSION_COMMIT_POLL_INTERVAL = 1.0
@@ -97,6 +100,7 @@ class QueueManager:
max_concurrent_external_parse: int = 4,
max_concurrent_add_resource: int = 4,
max_concurrent_session_commit: int = DEFAULT_MAX_CONCURRENT_SESSION_COMMIT,
+ max_concurrent_external_task: int = 10,
):
"""Initialize QueueManager."""
self._agfs = agfs
@@ -107,6 +111,7 @@ class QueueManager:
self._max_concurrent_external_parse = max_concurrent_external_parse
self._max_concurrent_add_resource = max_concurrent_add_resource
self._max_concurrent_session_commit = max_concurrent_session_commit
+ self._max_concurrent_external_task = max_concurrent_external_task
self._queues: Dict[str, NamedQueue] = {}
self._started = False
self._queue_threads: Dict[str, threading.Thread] = {}
@@ -205,6 +210,8 @@ class QueueManager:
return self._max_concurrent_add_resource
if queue_name == self.SESSION_COMMIT:
return self._max_concurrent_session_commit
+ if queue_name == self.EXTERNAL_TASK:
+ return self._max_concurrent_external_task
return self._max_concurrent_semantic
def _queue_worker_loop(
diff --git a/openviking_cli/utils/config/__init__.py b/openviking_cli/utils/config/__init__.py
index 4721fd532..0a2c1e9e4 100644
--- a/openviking_cli/utils/config/__init__.py
+++ b/openviking_cli/utils/config/__init__.py
@@ -56,6 +56,7 @@ from .git_config import GitConfig, GitLocalConfig, GitS3Config
from .grep_config import GrepConfig, GrepEngine
from .log_config import LogConfig
from .open_viking_config import (
+ CompileApiConfig,
OpenVikingConfig,
OpenVikingConfigSingleton,
get_openviking_config,
@@ -132,6 +133,7 @@ __all__ = [
"OPENVIKING_GO_PATH_ENV",
"OPENVIKING_GOPATH_ENV",
"OPENVIKING_GOPROXY_ENV",
+ "CompileApiConfig",
"OpenVikingConfig",
"OpenVikingConfigSingleton",
"OVCLIConfig",
diff --git a/openviking_cli/utils/config/open_viking_config.py b/openviking_cli/utils/config/open_viking_config.py
index dd96b0ace..39ad59f01 100644
--- a/openviking_cli/utils/config/open_viking_config.py
+++ b/openviking_cli/utils/config/open_viking_config.py
@@ -136,6 +136,27 @@ class ParserApiConfig(BaseModel):
return self
+class CompileApiConfig(BaseModel):
+ """Configuration for the external Compile task API."""
+
+ base_url: str = ""
+ gateway_token: str = ""
+ http_timeout_seconds: float = 10.0
+ poll_interval_ms: int = 30000
+ model_config = {"extra": "forbid"}
+
+ @model_validator(mode="after")
+ def _validate(self) -> "CompileApiConfig":
+ if self.base_url and "://" not in self.base_url:
+ raise ValueError("compile_api.base_url must include scheme (e.g., https://...)")
+ if self.http_timeout_seconds <= 0:
+ raise ValueError("compile_api.http_timeout_seconds must be > 0")
+ if self.poll_interval_ms <= 0:
+ raise ValueError("compile_api.poll_interval_ms must be > 0")
+ self.base_url = self.base_url.rstrip("/")
+ return self
+
+
class OpenVikingConfig(BaseModel):
"""Main configuration for OpenViking."""
@@ -255,6 +276,11 @@ class OpenVikingConfig(BaseModel):
description="Third-party parser API configuration (files/responses)",
)
+ compile_api: CompileApiConfig = Field(
+ default_factory=CompileApiConfig,
+ description="External Compile task API configuration",
+ )
+
connector: ConnectorConfig = Field(
default_factory=ConnectorConfig,
description="External Connector service configuration for data import",
diff --git a/openviking_cli/utils/config/queue_worker_config.py b/openviking_cli/utils/config/queue_worker_config.py
index 406ef513b..4553e11eb 100644
--- a/openviking_cli/utils/config/queue_worker_config.py
+++ b/openviking_cli/utils/config/queue_worker_config.py
@@ -31,11 +31,12 @@ class QueueWorkersConfig(BaseModel):
"""Runtime limits for QueueFS consumers."""
external_parse: QueueWorkerConfig = Field(default_factory=QueueWorkerConfig)
- add_resource: AddResourceQueueWorkerConfig = Field(
- default_factory=AddResourceQueueWorkerConfig
- )
+ add_resource: AddResourceQueueWorkerConfig = Field(default_factory=AddResourceQueueWorkerConfig)
session_commit: QueueWorkerConfig = Field(
default_factory=lambda: QueueWorkerConfig(max_concurrent=8)
)
+ external_task: QueueWorkerConfig = Field(
+ default_factory=lambda: QueueWorkerConfig(max_concurrent=10)
+ )
model_config = {"extra": "forbid"}
diff --git a/sdk/go/client_test.go b/sdk/go/client_test.go
index 948ca131c..45f642220 100644
--- a/sdk/go/client_test.go
+++ b/sdk/go/client_test.go
@@ -1666,27 +1666,55 @@ func TestSessionExistsHandlesNotFound(t *testing.T) {
}
}
-func TestListTasksRequest(t *testing.T) {
+func TestCompileAndListTasksRequests(t *testing.T) {
client, closeServer := testClient(t, http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
- if r.Method != http.MethodGet {
- t.Fatalf("method = %s", r.Method)
- }
- if r.URL.Path != "/api/v1/tasks" {
+ switch r.URL.Path {
+ case "/api/v1/compile":
+ if r.Method != http.MethodPost {
+ t.Fatalf("method = %s", r.Method)
+ }
+ body := readJSONBody(t, r)
+ if !reflect.DeepEqual(body["from"], []any{"viking://resources/source"}) ||
+ body["to"] != "viking://resources/output" ||
+ body["skill"] != "viking://agent/skills/wiki" ||
+ !reflect.DeepEqual(body["args"], map[string]any{"model_name": "endpoint-1"}) {
+ t.Fatalf("body = %#v", body)
+ }
+ writeOK(t, w, map[string]any{"task_id": "cmp_1"})
+ case "/api/v1/tasks":
+ if r.Method != http.MethodGet {
+ t.Fatalf("method = %s", r.Method)
+ }
+ query := r.URL.Query()
+ if query.Get("task_type") != "session_commit" ||
+ query.Get("status") != "running" ||
+ query.Get("resource_id") != "session-1" ||
+ query.Get("limit") != "20" {
+ t.Fatalf("query = %s", r.URL.RawQuery)
+ }
+ writeOK(t, w, []map[string]any{
+ {"task_id": "task-1", "status": "running"},
+ })
+ default:
t.Fatalf("path = %s", r.URL.Path)
}
- query := r.URL.Query()
- if query.Get("task_type") != "session_commit" ||
- query.Get("status") != "running" ||
- query.Get("resource_id") != "session-1" ||
- query.Get("limit") != "20" {
- t.Fatalf("query = %s", r.URL.RawQuery)
- }
- writeOK(t, w, []map[string]any{
- {"task_id": "task-1", "status": "running"},
- })
}))
defer closeServer()
+ compiled, err := client.Compile(
+ context.Background(),
+ []string{"viking://resources/source"},
+ "viking://resources/output",
+ "viking://agent/skills/wiki",
+ &CompileOptions{Args: map[string]any{"model_name": "endpoint-1"}},
+ )
+ if err != nil {
+ t.Fatal(err)
+ }
+ if compiled["task_id"] != "cmp_1" {
+ t.Fatalf("compiled = %#v", compiled)
+ }
+
tasks, err := client.ListTasks(context.Background(), &ListTasksOptions{
TaskType: "session_commit",
Status: "running",
diff --git a/sdk/go/compile.go b/sdk/go/compile.go
new file mode 100644
index 000000000..52f40e19d
--- /dev/null
+++ b/sdk/go/compile.go
@@ -0,0 +1,34 @@
+package openviking
+
+import (
+ "context"
+ "net/http"
+)
+
+// Compile starts an asynchronous Compile task.
+func (c *Client) Compile(
+ ctx context.Context,
+ fromURIs []string,
+ to string,
+ skill string,
+ opts *CompileOptions,
+) (map[string]any, error) {
+ if opts == nil {
+ opts = &CompileOptions{}
+ }
+ payload := map[string]any{
+ "from": fromURIs,
+ "to": to,
+ "skill": skill,
+ }
+ setString(payload, "reason", opts.Reason)
+ if len(opts.Args) > 0 {
+ payload["args"] = opts.Args
+ }
+ if err := mergeExtraProtected(payload, opts.Extra, "reason", "args"); err != nil {
+ return nil, err
+ }
+ var result map[string]any
+ err := c.doJSON(ctx, http.MethodPost, "/api/v1/compile", nil, payload, &result)
+ return result, err
+}
diff --git a/sdk/go/types.go b/sdk/go/types.go
index 74ab1cd0d..b6601c975 100644
--- a/sdk/go/types.go
+++ b/sdk/go/types.go
@@ -57,6 +57,13 @@ type AddSkillOptions struct {
TargetURI any
}
+// CompileOptions controls Compile.
+type CompileOptions struct {
+ Reason string
+ Args map[string]any
+ Extra map[string]any
+}
+
// AdminCreateAccountOptions controls AdminCreateAccountWithOptions.
type AdminCreateAccountOptions struct {
UserConfig map[string]any
diff --git a/sdk/python/openviking_sdk/__init__.py b/sdk/python/openviking_sdk/__init__.py
index c3e4bdc59..c5975c578 100644
--- a/sdk/python/openviking_sdk/__init__.py
+++ b/sdk/python/openviking_sdk/__init__.py
@@ -15,6 +15,7 @@ from .options import (
BatchAddMessagesOptions,
BatchWriteOptions,
CommitSessionOptions,
+ CompileOptions,
CreateSessionOptions,
ExperienceOutcomeOptions,
ExperienceTrajectoryOptions,
@@ -41,6 +42,7 @@ __all__ = [
"BatchAddMessagesOptions",
"BatchWriteOptions",
"CommitSessionOptions",
+ "CompileOptions",
"ConflictError",
"ContextPart",
"CreateSessionOptions",
diff --git a/sdk/python/openviking_sdk/client.py b/sdk/python/openviking_sdk/client.py
index ae1e33f64..a1f3bbb10 100644
--- a/sdk/python/openviking_sdk/client.py
+++ b/sdk/python/openviking_sdk/client.py
@@ -47,6 +47,7 @@ from .options import (
BatchAddMessagesOptions,
BatchWriteOptions,
CommitSessionOptions,
+ CompileOptions,
CreateSessionOptions,
ExperienceOutcomeOptions,
ExperienceTrajectoryOptions,
@@ -1543,6 +1544,21 @@ class AsyncHTTPClient:
return None
return self._handle_response(response)
+ async def compile(
+ self,
+ from_uris: List[str],
+ to: str,
+ skill: str,
+ options: Optional[CompileOptions] = None,
+ ) -> Dict[str, Any]:
+ payload = self._build_options_payload(
+ options,
+ CompileOptions,
+ fixed={"from": list(from_uris), "to": to, "skill": skill},
+ )
+ response = await self._request("POST", "/api/v1/compile", json=payload)
+ return self._handle_response(response)
+
async def cancel_task(self, task_id: str) -> Dict[str, Any]:
response = await self._request("POST", f"/api/v1/tasks/{task_id}/cancel")
return self._handle_response(response)
@@ -2664,6 +2680,15 @@ class SyncHTTPClient:
def get_task(self, task_id: str) -> Optional[Dict[str, Any]]:
return run_async(self._async_client.get_task(task_id))
+ def compile(
+ self,
+ from_uris: List[str],
+ to: str,
+ skill: str,
+ options: Optional[CompileOptions] = None,
+ ) -> Dict[str, Any]:
+ return run_async(self._async_client.compile(from_uris, to, skill, options))
+
def cancel_task(self, task_id: str) -> Dict[str, Any]:
return run_async(self._async_client.cancel_task(task_id))
diff --git a/sdk/python/openviking_sdk/options.py b/sdk/python/openviking_sdk/options.py
index 59e1da7d4..96899be7c 100644
--- a/sdk/python/openviking_sdk/options.py
+++ b/sdk/python/openviking_sdk/options.py
@@ -97,6 +97,11 @@ class BatchWriteOptions(_ExtraOptions, total=False):
telemetry: Any
+class CompileOptions(_ExtraOptions, total=False):
+ reason: str
+ args: Dict[str, Any]
+
+
class SetTagsOptions(_ExtraOptions, total=False):
telemetry: Any
diff --git a/sdk/python/tests/test_async_client_behaviors.py b/sdk/python/tests/test_async_client_behaviors.py
index 0220d043f..ec7d61081 100644
--- a/sdk/python/tests/test_async_client_behaviors.py
+++ b/sdk/python/tests/test_async_client_behaviors.py
@@ -602,12 +602,35 @@ def test_sync_http_client_declares_common_sync_methods_explicitly():
"get_skill",
"update_skill",
"delete_skill",
+ "compile",
"get_task",
"list_tasks",
"admin_list_accounts",
]:
assert method_name in explicit_methods, method_name
+ client = SyncHTTPClient(url="http://localhost:1933")
+ client._async_client._request = AsyncMock(return_value=object())
+ client._async_client._handle_response = lambda _response: {"task_id": "cmp_1"}
+ result = client.compile(
+ ["viking://resources/source"],
+ "viking://resources/output",
+ "viking://agent/skills/wiki",
+ options={"args": {"model_name": "endpoint-1"}},
+ )
+
+ assert result == {"task_id": "cmp_1"}
+ client._async_client._request.assert_awaited_once_with(
+ "POST",
+ "/api/v1/compile",
+ json={
+ "from": ["viking://resources/source"],
+ "to": "viking://resources/output",
+ "skill": "viking://agent/skills/wiki",
+ "args": {"model_name": "endpoint-1"},
+ },
+ )
+
def test_sync_http_client_session_must_exist_checks_existence():
client = SyncHTTPClient(url="http://localhost:1933")
diff --git a/sdk/typescript/src/client.ts b/sdk/typescript/src/client.ts
index b356f3950..50f2d65ee 100644
--- a/sdk/typescript/src/client.ts
+++ b/sdk/typescript/src/client.ts
@@ -13,6 +13,7 @@ import type {
BatchWriteOptions,
ClientConfig,
CommitSessionOptions,
+ CompileOptions,
CreateSessionOptions,
ExperienceOutcomeOptions,
ExperienceTrajectoryOptions,
@@ -937,6 +938,28 @@ export class OpenVikingClient {
);
return result.uri;
}
+ /** Start an asynchronous Compile task. */
+ compile(
+ fromUris: string[],
+ to: string,
+ skill: string,
+ options: CompileOptions = {},
+ ): Promise<JsonObject> {
+ const body = compact({
+ from: fromUris,
+ to,
+ skill,
+ reason: options.reason,
+ args:
+ options.args && Object.keys(options.args).length
+ ? options.args
+ : undefined,
+ });
+ return this.request("POST", "/api/v1/compile", {
+ body: mergeExtra(body, options.extra, ["reason", "args"]),
+ });
+ }
+
/** Get a background task. */
async getTask(taskId: string): Promise<JsonObject | null> {
try {
diff --git a/sdk/typescript/src/types.ts b/sdk/typescript/src/types.ts
index 33859c1c8..7bfbf8674 100644
--- a/sdk/typescript/src/types.ts
+++ b/sdk/typescript/src/types.ts
@@ -111,6 +111,12 @@ export interface BatchWriteOperation {
export interface BatchWriteOptions extends WaitOptions {
extra?: JsonObject;
}
+/** Compile request options. */
+export interface CompileOptions {
+ reason?: string;
+ args?: JsonObject;
+ extra?: JsonObject;
+}
/** Retrieval tag update options. */
export interface SetTagsOptions {
mode?: "replace" | "append";
diff --git a/sdk/typescript/tests/client.test.ts b/sdk/typescript/tests/client.test.ts
index 558958f89..febd53756 100644
--- a/sdk/typescript/tests/client.test.ts
+++ b/sdk/typescript/tests/client.test.ts
@@ -781,9 +781,10 @@ describe("OpenVikingClient", () => {
});
});
- it("uses Go SDK defaults for skill details and returns null for missing tasks", async () => {
+ it("uses public Compile and task routes with SDK-compatible options", async () => {
const fetcher = vi
.fn<typeof fetch>()
+ .mockResolvedValueOnce(ok({ task_id: "cmp_1" }))
.mockResolvedValueOnce(ok({ name: "demo" }))
.mockResolvedValueOnce(
new Response(
@@ -799,10 +800,27 @@ describe("OpenVikingClient", () => {
fetch: fetcher,
});
+ await expect(
+ client.compile(
+ ["viking://resources/source"],
+ "viking://resources/output",
+ "viking://agent/skills/wiki",
+ { args: { model_name: "endpoint-1" } },
+ ),
+ ).resolves.toEqual({ task_id: "cmp_1" });
await client.getSkill("demo");
await expect(client.getTask("missing")).resolves.toBeNull();
- const skillUrl = new URL(String(fetcher.mock.calls[0]![0]));
+ expect(String(fetcher.mock.calls[0]![0])).toBe(
+ "https://example.com/api/v1/compile",
+ );
+ expect(JSON.parse(String(fetcher.mock.calls[0]![1]?.body))).toEqual({
+ from: ["viking://resources/source"],
+ to: "viking://resources/output",
+ skill: "viking://agent/skills/wiki",
+ args: { model_name: "endpoint-1" },
+ });
+ const skillUrl = new URL(String(fetcher.mock.calls[1]![0]));
expect(skillUrl.searchParams.get("include_files")).toBe("true");
expect(skillUrl.searchParams.get("include_source")).toBe("false");
});
diff --git a/tests/server/test_bot_proxy_auth.py b/tests/server/test_bot_proxy_auth.py
index 153a995e3..ea811c39d 100644
--- a/tests/server/test_bot_proxy_auth.py
+++ b/tests/server/test_bot_proxy_auth.py
@@ -3,7 +3,6 @@
"""Regression tests for bot proxy endpoint auth enforcement."""
-import json
from types import SimpleNamespace
import httpx
@@ -11,9 +10,16 @@ import pytest
from fastapi import FastAPI
import openviking.server.routers.bot as bot_router_module
+import openviking.server.routers.compile as compile_router_module
+import openviking.service.compile_service as compile_service_module
+import openviking.service.external_task_service as external_task_service_module
from openviking.server.auth.plugins import DevAuthPlugin, TrustedAuthPlugin
from openviking.server.config import ServerConfig
from openviking.server.identity import AuthMode
+from openviking.service.compile_service import CompileService
+from openviking.service.external_task_service import ExternalTaskService
+from openviking.service.task_tracker import TaskRecord, TaskStatus
+from openviking_cli.utils.config.open_viking_config import CompileApiConfig
def test_set_bot_api_key_updates_module_state():
@@ -215,69 +221,32 @@ async def test_chat_proxy_forwards_trusted_request_without_root_api_key(monkeypa
@pytest.mark.asyncio
-async def test_compile_proxy_forwards_create_and_status_identity(monkeypatch):
- forwarded = []
-
- class FakeResponse:
- def __init__(self, payload, status_code=200):
- self._payload = payload
- self.status_code = status_code
- self.text = json.dumps(payload)
-
- @property
- def is_success(self):
- return 200 <= self.status_code < 300
-
- def json(self):
- return self._payload
-
- class FakeClient:
- async def __aenter__(self):
- return self
-
- async def __aexit__(self, exc_type, exc, tb):
- return None
-
- async def post(self, url, json, headers, timeout):
- forwarded.append(("POST", url, json, headers, timeout))
- if url.endswith("/cancel"):
- return FakeResponse(
- {
- "task_id": "cmp_1",
- "status": "cancelled",
- "stage": "cancelled",
- "created_at": "2026-07-20T00:00:00Z",
- "updated_at": "2026-07-20T00:00:02Z",
- }
- )
- return FakeResponse(
- {
- "task_id": "cmp_1",
- "status": "accepted",
- "to": "viking://resources/wiki",
- },
- 202,
+async def test_compile_route_uses_ov_owned_task_and_rejects_legacy_routes(monkeypatch):
+ calls = {}
+
+ class FakeCompileService:
+ async def create(self, body, *, connection, ctx):
+ calls["request"] = body.model_dump(mode="json", by_alias=True)
+ calls["connection"] = connection
+ calls["owner"] = (ctx.account_id, ctx.user.user_id)
+ return TaskRecord(
+ task_id="cmp_1",
+ task_type="compile",
+ status=TaskStatus.PENDING,
+ stage="queued",
+ resource_id="viking://resources/source",
+ account_id="acct",
+ user_id="alice",
+ meta={"request": {"to": "viking://resources/wiki"}},
)
- async def get(self, url, headers, timeout):
- forwarded.append(("GET", url, None, headers, timeout))
- return FakeResponse(
- {
- "task_id": "cmp_1",
- "status": "running",
- "stage": "agent",
- "created_at": "2026-07-20T00:00:00Z",
- "updated_at": "2026-07-20T00:00:01Z",
- }
- )
-
- monkeypatch.setattr(bot_router_module, "BOT_API_URL", "http://127.0.0.1:18790")
- monkeypatch.setattr(bot_router_module, "BOT_API_KEY", "gateway-secret")
- monkeypatch.setattr(bot_router_module, "_create_bot_proxy_client", lambda: FakeClient())
+ service = SimpleNamespace(compile=FakeCompileService())
+ monkeypatch.setattr(compile_router_module, "get_service", lambda: service)
app = FastAPI()
app.state.config = ServerConfig(auth_mode="trusted", host="127.0.0.1", port=1944)
app.state.auth_plugin = TrustedAuthPlugin()
+ app.include_router(compile_router_module.router)
app.include_router(bot_router_module.router, prefix="/bot/v1")
transport = httpx.ASGITransport(app=app)
headers = {
@@ -287,7 +256,7 @@ async def test_compile_proxy_forwards_create_and_status_identity(monkeypatch):
}
async with httpx.AsyncClient(transport=transport, base_url="http://testserver") as client:
created = await client.post(
- "/bot/v1/compile",
+ "/api/v1/compile",
headers=headers,
json={
"from": ["viking://resources/source"],
@@ -295,90 +264,246 @@ async def test_compile_proxy_forwards_create_and_status_identity(monkeypatch):
"skill": "viking://agent/skills/wiki",
},
)
- status_response = await client.get("/bot/v1/compile/cmp_1", headers=headers)
- cancel_response = await client.post(
+ legacy_created = await client.post("/bot/v1/compile", headers=headers, json={})
+ legacy_status = await client.get("/bot/v1/compile/cmp_1", headers=headers)
+ legacy_cancel = await client.post(
"/bot/v1/compile/cmp_1/cancel",
headers=headers,
)
assert created.status_code == 202
assert created.json()["result"]["task_id"] == "cmp_1"
- assert status_response.json()["result"]["stage"] == "agent"
- assert cancel_response.json()["result"]["status"] == "cancelled"
- post = forwarded[0]
- assert post[1].endswith("/bot/v1/compile")
- assert post[2]["openviking_connection"]["api_key"] == "active-user-key"
- get = forwarded[1]
- assert get[1].endswith("/bot/v1/compile/cmp_1")
- assert get[3]["X-Gateway-Token"] == "gateway-secret"
- assert get[3]["X-API-Key"] == "active-user-key"
- assert get[3]["X-OpenViking-Account"] == "acct"
- assert get[3]["X-OpenViking-User"] == "alice"
- cancel = forwarded[2]
- assert cancel[1].endswith("/bot/v1/compile/cmp_1/cancel")
- assert cancel[2] == {}
- assert cancel[3]["X-Gateway-Token"] == "gateway-secret"
- assert cancel[3]["X-API-Key"] == "active-user-key"
+ assert legacy_created.status_code == 400
+ assert "POST /api/v1/compile" in legacy_created.json()["detail"]
+ assert "GET /api/v1/tasks/{task_id}" in legacy_created.json()["detail"]
+ assert legacy_status.status_code == 400
+ assert "GET /api/v1/tasks/{task_id}" in legacy_status.json()["detail"]
+ assert legacy_cancel.status_code == 400
+ assert "POST /api/v1/tasks/{task_id}/cancel" in legacy_cancel.json()["detail"]
+ assert calls["connection"] == {"api_key": "active-user-key"}
+ assert calls["owner"] == ("acct", "alice")
@pytest.mark.asyncio
-async def test_compile_proxy_supports_no_key_dev_mode(monkeypatch):
- forwarded = {}
+async def test_compile_api_client_session_protocol_retry_and_cancellation(monkeypatch):
+ forwarded = []
+ response_status = {
+ "cancel": "cancelled",
+ "submit_failures": 0,
+ "cancel_failures": 0,
+ "poll": [],
+ }
class FakeResponse:
- status_code = 202
- text = '{"task_id":"cmp_dev"}'
- is_success = True
-
- @staticmethod
- def json():
- return {
- "task_id": "cmp_dev",
- "status": "accepted",
- "to": "viking://resources/wiki",
- }
+ def __init__(self, body, status_code=202):
+ self._body = body
+ self.status_code = status_code
+ self.is_success = status_code < 400
+
+ def json(self):
+ return self._body
class FakeClient:
+ def __init__(self, **kwargs):
+ self.kwargs = kwargs
+
async def __aenter__(self):
return self
async def __aexit__(self, exc_type, exc, tb):
return None
- async def post(self, url, json, headers, timeout):
- from vikingbot.compile.models import CompileRequest
-
- CompileRequest.model_validate(json)
- forwarded.update(url=url, body=json, headers=headers, timeout=timeout)
- return FakeResponse()
-
- monkeypatch.setattr(bot_router_module, "BOT_API_URL", "http://127.0.0.1:18790")
- monkeypatch.setattr(bot_router_module, "BOT_API_KEY", "")
- monkeypatch.setattr(bot_router_module, "_create_bot_proxy_client", lambda: FakeClient())
-
- app = FastAPI()
- app.state.config = ServerConfig(auth_mode="dev", host="127.0.0.1", port=1944)
- app.state.auth_plugin = DevAuthPlugin()
- app.include_router(bot_router_module.router, prefix="/bot/v1")
+ async def request(self, method, url, headers, json):
+ forwarded.append({"method": method, "url": url, "body": json, "headers": headers})
+ if url.endswith("/runtime/v1/tasks"):
+ if response_status["submit_failures"]:
+ response_status["submit_failures"] -= 1
+ return FakeResponse({"detail": "temporarily unavailable"}, status_code=503)
+ return FakeResponse({"session_id": "ma-session-1"})
+ if url.endswith("/runtime/v1/tasks/cancel"):
+ if response_status["cancel_failures"]:
+ response_status["cancel_failures"] -= 1
+ return FakeResponse({"detail": "temporarily unavailable"}, status_code=503)
+ status = response_status["cancel"]
+ return FakeResponse(
+ {
+ "status": status,
+ "stage": f"compile: {status}",
+ "error": None,
+ "meta": {},
+ }
+ )
+ status = response_status["poll"].pop(0) if response_status["poll"] else "running"
+ return FakeResponse(
+ {
+ "status": status,
+ "stage": f"compile: {status}",
+ "error": None,
+ "meta": {"token_usage": {"total_tokens": 12}},
+ "result": {"output": "wiki"} if status == "completed" else None,
+ }
+ )
- async with httpx.AsyncClient(
- transport=httpx.ASGITransport(app=app),
- base_url="http://testserver",
- ) as client:
- response = await client.post(
- "/bot/v1/compile",
- json={
+ monkeypatch.setattr(compile_service_module.httpx, "AsyncClient", FakeClient)
+ tasks = ExternalTaskService()
+ service = CompileService(
+ CompileApiConfig(
+ base_url="https://compile.example.com",
+ ),
+ tasks,
+ SimpleNamespace(),
+ )
+ tasks.register(service)
+ public_payload, private_payload = service._split_payload(
+ compile_service_module.CompileRequest.model_validate(
+ {
"from": ["viking://resources/source"],
"to": "viking://resources/wiki",
"skill": "viking://agent/skills/wiki",
- },
+ "args": {"model_name": "model-1", "user_key": "model-user-key"},
+ }
)
+ )
+ assert public_payload["args"] == {"model_name": "model-1"}
+ assert private_payload == {"args": {"user_key": "model-user-key"}}
+ external_task_id = await service.submit(
+ "cmp_ov_1",
+ {
+ "from": ["viking://resources/source"],
+ "to": "viking://resources/wiki",
+ "skill": "viking://agent/skills/wiki",
+ },
+ {
+ "args": {"user_key": "model-user-key"},
+ },
+ {"api_key": "active-user-key"},
+ )
+ status_snapshot = await service.get(
+ external_task_id,
+ {"api_key": "active-user-key"},
+ )
+ cancel_snapshot = await service.cancel(
+ external_task_id,
+ {"api_key": "active-user-key"},
+ )
+
+ assert external_task_id == "ma-session-1"
+ assert [request["url"] for request in forwarded] == [
+ "https://compile.example.com/runtime/v1/tasks",
+ "https://compile.example.com/runtime/v1/tasks/status",
+ "https://compile.example.com/runtime/v1/tasks/cancel",
+ ]
+ assert all(request["method"] == "POST" for request in forwarded)
+ assert "X-Gateway-Token" not in forwarded[0]["headers"]
+ assert forwarded[0]["headers"]["Idempotency-Key"] == "cmp_ov_1"
+ assert forwarded[0]["headers"]["X-API-Key"] == "active-user-key"
+ assert forwarded[0]["body"] == {
+ "task_type": "compile",
+ "payload": {
+ "from": ["viking://resources/source"],
+ "to": "viking://resources/wiki",
+ "skill": "viking://agent/skills/wiki",
+ "args": {"user_key": "model-user-key"},
+ },
+ }
+ assert forwarded[1]["body"] == {"session_id": "ma-session-1"}
+ assert status_snapshot.meta == {"token_usage": {"total_tokens": 12}}
+ assert cancel_snapshot.status == "cancelled"
+
+ class Tracker:
+ def __init__(self):
+ self.task = TaskRecord(
+ task_id="cmp_ov_1",
+ task_type="compile",
+ status=TaskStatus.RUNNING,
+ stage="compile: running",
+ account_id="acct",
+ user_id="alice",
+ meta={
+ "request": {
+ "from": ["viking://resources/source"],
+ "to": "viking://resources/wiki",
+ "skill": "viking://agent/skills/wiki",
+ },
+ "token_usage": {"total_tokens": 12},
+ },
+ )
+ self.auth = {
+ "openviking_connection": {"api_key": "active-user-key"},
+ "external_request_private": {},
+ }
+ self.stage = None
+ self.stage_updates = []
+ self.error = None
+
+ async def get(self, *args, **kwargs):
+ return self.task
+
+ async def get_task_auth(self, *args, **kwargs):
+ return self.auth
+
+ async def start(self, *args, **kwargs):
+ return None
- assert response.status_code == 202
- assert forwarded["url"].endswith("/bot/v1/compile")
- assert "user_id" not in forwarded["body"]
- assert "openviking_connection" not in forwarded["body"]
- assert "X-API-Key" not in forwarded["headers"]
+ async def update_task_auth(self, _task_id, values, **kwargs):
+ self.auth.update(values)
+
+ async def update_stage(self, _task_id, stage, **kwargs):
+ self.stage = stage
+ self.stage_updates.append(stage)
+ self.task.stage = stage
+
+ async def fail(self, _task_id, error, **kwargs):
+ self.error = error
+ self.task.status = TaskStatus.FAILED
+
+ async def complete(self, _task_id, result, **kwargs):
+ self.task.result = result
+ self.task.status = TaskStatus.COMPLETED
+
+ async def record_cancelled(self, _task_id, **kwargs):
+ self.task.status = TaskStatus.CANCELLED
+
+ def is_cancellation_requested(self, _task_id):
+ return False
+
+ async def no_sleep(_delay):
+ return None
+
+ monkeypatch.setattr(external_task_service_module.asyncio, "sleep", no_sleep)
+ tracker = Tracker()
+ monkeypatch.setattr(external_task_service_module, "get_task_tracker", lambda: tracker)
+ forwarded.clear()
+ response_status["submit_failures"] = 1
+ response_status["poll"] = ["running", "completed"]
+
+ await tasks.execute("cmp_ov_1", "acct", "alice")
+
+ assert [request["url"] for request in forwarded] == [
+ "https://compile.example.com/runtime/v1/tasks",
+ "https://compile.example.com/runtime/v1/tasks",
+ "https://compile.example.com/runtime/v1/tasks/status",
+ "https://compile.example.com/runtime/v1/tasks/status",
+ ]
+ assert forwarded[0]["headers"]["Idempotency-Key"] == "cmp_ov_1"
+ assert forwarded[1]["headers"]["Idempotency-Key"] == "cmp_ov_1"
+ assert tracker.stage_updates == ["compile: completed"]
+ assert tracker.task.status == TaskStatus.COMPLETED
+ assert tracker.task.result == {"output": "wiki"}
+
+ forwarded.clear()
+ response_status["cancel"] = "cancelling"
+ response_status["cancel_failures"] = 3
+ response_status["poll"] = ["cancelling"] * 4 + ["cancelled"]
+ tracker.task.status = TaskStatus.CANCELLING
+ tracker.task.stage = "compile: running"
+ tracker.stage_updates.clear()
+
+ await tasks.cancel_recovered("cmp_ov_1", "acct", "alice")
+
+ assert tracker.task.status == TaskStatus.CANCELLED
+ assert response_status["cancel_failures"] == 0
+ assert response_status["poll"] == []
@pytest.mark.asyncio
diff --git a/tests/test_config_loader.py b/tests/test_config_loader.py
index f7e745695..c51e66f1e 100644
--- a/tests/test_config_loader.py
+++ b/tests/test_config_loader.py
@@ -18,7 +18,11 @@ from openviking_cli.utils.config.config_loader import (
require_config,
resolve_config_path,
)
-from openviking_cli.utils.config.open_viking_config import OpenVikingConfig, ParserApiConfig
+from openviking_cli.utils.config.open_viking_config import (
+ CompileApiConfig,
+ OpenVikingConfig,
+ ParserApiConfig,
+)
from openviking_cli.utils.config.parser_config import CodeHostingConfig, DirectoryConfig
from openviking_cli.utils.config.queue_worker_config import QueueWorkersConfig
@@ -128,6 +132,7 @@ def test_runtime_concurrency_uses_scope_specific_defaults():
assert config.queue_workers.add_resource.max_concurrent == 4
assert config.queue_workers.add_resource.file_vectorization_concurrency == 8
assert config.queue_workers.session_commit.max_concurrent == 8
+ assert config.queue_workers.external_task.max_concurrent == 10
assert config.reindex.file_vectorization_concurrency == 8
@@ -141,6 +146,7 @@ def test_runtime_concurrency_accepts_separate_values():
"file_vectorization_concurrency": 12,
},
"session_commit": {"max_concurrent": 50},
+ "external_task": {"max_concurrent": 11},
},
"reindex": {"file_vectorization_concurrency": 16},
}
@@ -150,6 +156,7 @@ def test_runtime_concurrency_accepts_separate_values():
assert config.queue_workers.add_resource.max_concurrent == 7
assert config.queue_workers.add_resource.file_vectorization_concurrency == 12
assert config.queue_workers.session_commit.max_concurrent == 50
+ assert config.queue_workers.external_task.max_concurrent == 11
assert config.reindex.file_vectorization_concurrency == 16
@@ -161,11 +168,19 @@ def test_queue_worker_concurrency_rejects_non_positive_value(value):
assert exc_info.value.errors()[0]["type"] == "greater_than"
-def test_parser_api_rejects_worker_max_concurrent():
+def test_parser_and_compile_api_validation():
with pytest.raises(ValueError) as exc_info:
ParserApiConfig(max_concurrent=9)
assert exc_info.value.errors()[0]["type"] == "extra_forbidden"
+ with pytest.raises(ValueError, match="compile_api.base_url must include scheme"):
+ CompileApiConfig(base_url="compile.example.com")
+
+ config = CompileApiConfig(
+ base_url="https://compile.example.com/",
+ )
+ assert config.base_url == "https://compile.example.com"
+ assert config.gateway_token == ""
def test_parser_api_upload_defaults():
diff --git a/tests/test_task_tracker.py b/tests/test_task_tracker.py
index 27fa096a6..9b1320d49 100644
--- a/tests/test_task_tracker.py
+++ b/tests/test_task_tracker.py
@@ -77,15 +77,13 @@ class _FakeAgfs:
data,
max_retries: int = 3,
*,
- fs_ctx=None,
- auto_pathlock: bool = True,
+ ctx=None,
):
self.write_calls.append(
{
"path": path,
"max_retries": max_retries,
- "fs_ctx": fs_ctx,
- "auto_pathlock": auto_pathlock,
+ "ctx": ctx,
}
)
if isinstance(data, str):
@@ -128,16 +126,14 @@ class _FakeAgfs:
recursive: bool = False,
force: bool = False,
*,
- fs_ctx=None,
- auto_pathlock: bool = True,
+ ctx=None,
):
self.rm_calls.append(
{
"path": path,
"recursive": recursive,
"force": force,
- "fs_ctx": fs_ctx,
- "auto_pathlock": auto_pathlock,
+ "ctx": ctx,
}
)
if self.fail_rm:
@@ -175,7 +171,7 @@ async def test_start_task(tracker: TaskTracker):
assert retrieved.status == TaskStatus.RUNNING
-async def test_update_stage(tracker: TaskTracker):
+async def test_update_stage_and_record_owner_cancelled(tracker: TaskTracker):
task = await tracker.create("add_resource", **_owner_kwargs())
await tracker.start(task.task_id, stage="queued")
await tracker.update_stage(task.task_id, "parsing")
@@ -184,6 +180,12 @@ async def test_update_stage(tracker: TaskTracker):
assert retrieved.status == TaskStatus.RUNNING
assert retrieved.stage == "parsing"
+ await tracker.record_cancelled(task.task_id)
+ cancelled = await tracker.get(task.task_id)
+ assert cancelled is not None
+ assert cancelled.status == TaskStatus.CANCELLED
+ assert cancelled.stage == "cancelled"
+
async def test_complete_task(tracker: TaskTracker):
task = await tracker.create("session_commit", resource_id="s1", **_owner_kwargs())
@@ -351,10 +353,9 @@ async def test_list_can_hide_internal_tasks_before_limit(tracker: TaskTracker):
internal = await tracker.create("add_resource", meta={"internal": True}, **_owner_kwargs())
assert [task.task_id for task in await tracker.list_tasks(limit=1)] == [internal.task_id]
- assert [
- task.task_id
- for task in await tracker.list_tasks(limit=1, include_internal=False)
- ] == [visible.task_id]
+ assert [task.task_id for task in await tracker.list_tasks(limit=1, include_internal=False)] == [
+ visible.task_id
+ ]
async def test_list_order_most_recent_first(tracker: TaskTracker):
@@ -440,6 +441,16 @@ async def test_to_dict(tracker: TaskTracker):
"provider": "git_http_basic",
"password": "secret",
}
+ await tracker.update_task_auth(
+ task.task_id,
+ {"external_task_id": "session-1"},
+ **_owner_kwargs(),
+ )
+ assert await tracker.get_task_auth(task.task_id, **_owner_kwargs()) == {
+ "provider": "git_http_basic",
+ "password": "secret",
+ "external_task_id": "session-1",
+ }
assert (await tracker.get(task.task_id, **_owner_kwargs())).auth == {}
assert (await tracker.list_tasks(**_owner_kwargs()))[0].auth == {}
@@ -505,7 +516,7 @@ async def test_evict_keeps_cached_task_when_persistent_delete_fails():
assert await tracker.get(t.task_id) is None
assert await tracker._store.get(t.task_id, **_owner_kwargs()) is None
- assert all(call["auto_pathlock"] is False for call in agfs.rm_calls)
+ assert all(call["ctx"]["disable_auto_pathlock"] == "true" for call in agfs.rm_calls)
async def test_evict_keeps_recent_completed(tracker: TaskTracker):
@@ -583,7 +594,7 @@ async def test_persistent_store_writes_task_record_json():
raw = agfs.files[f"/local/acme/_system/tasks/alice/{task.task_id}.json"]
payload = json.loads(raw.decode("utf-8"))
- assert agfs.write_calls[-1]["auto_pathlock"] is False
+ assert agfs.write_calls[-1]["ctx"]["disable_auto_pathlock"] == "true"
assert payload["task_id"] == task.task_id
assert payload["task_type"] == "add_resource"
assert payload["account_id"] == "acme"
@@ -600,7 +611,7 @@ async def test_persistent_store_writes_task_record_json():
agfs.files[f"/local/acme/_system/tasks/alice/{task.task_id}.json"].decode("utf-8")
)
assert terminal_payload["auth"] == {}
- assert all(call["auto_pathlock"] is False for call in agfs.write_calls)
+ assert all(call["ctx"]["disable_auto_pathlock"] == "true" for call in agfs.write_calls)
async def test_persistent_store_keeps_tasktracker_tasks_dict():
@@ -650,7 +661,7 @@ async def test_persistent_store_ignores_existing_task_dirs():
"/local/acme/_system/tasks/alice",
]
assert agfs.mkdir_calls == first_mkdir_calls
- assert all(call["auto_pathlock"] is False for call in agfs.write_calls)
+ assert all(call["ctx"]["disable_auto_pathlock"] == "true" for call in agfs.write_calls)
async def test_create_requires_owner(tracker: TaskTracker):
diff --git a/tests/unit/service/test_core_consistency.py b/tests/unit/service/test_core_consistency.py
index 77bd45c6f..3a915f539 100644
--- a/tests/unit/service/test_core_consistency.py
+++ b/tests/unit/service/test_core_consistency.py
@@ -28,10 +28,12 @@ def test_service_passes_queue_worker_concurrency_to_storage(monkeypatch) -> None
),
vlm=SimpleNamespace(max_concurrent=32),
parser_api=SimpleNamespace(),
+ compile_api=SimpleNamespace(base_url=""),
queue_workers=SimpleNamespace(
external_parse=SimpleNamespace(max_concurrent=9),
add_resource=SimpleNamespace(max_concurrent=7),
session_commit=SimpleNamespace(max_concurrent=5),
+ external_task=SimpleNamespace(max_concurrent=6),
),
git=object(),
)
@@ -57,6 +59,7 @@ def test_service_passes_queue_worker_concurrency_to_storage(monkeypatch) -> None
assert storage_calls[0][1]["max_concurrent_external_parse"] == 9
assert storage_calls[0][1]["max_concurrent_add_resource"] == 7
assert storage_calls[0][1]["max_concurrent_session_commit"] == 5
+ assert storage_calls[0][1]["max_concurrent_external_task"] == 6
def _service_with_fs(stat_result: dict) -> tuple[OpenVikingService, AsyncMock]: