ldcon 0.2.0__py3-none-any.whl

ldcon/agents/agent_background.py

@@ -0,0 +1,307 @@
+"""Host gateway for approved background current experiments; never raw I/O."""
+import fcntl
+import json
+import math
+import os
+from pathlib import Path
+import time
+
+from experiment_core.records import atomic_json, safe_id
+from ldcon.core.records import read_json
+from ldcon.agents.operating_mode_client import request as mode_read, revision as mode_revision, describe as owner_describe
+
+
+def control_root(root):
+    value = os.environ.get('LDCON_ADAPTIVE_ROOT')
+    if not value:
+        raise ValueError('Background adjustment unavailable: trusted adaptive root is not configured')
+    path = Path(value)
+    if (not path.is_absolute() or not path.is_dir() or path.resolve() != path
+            or path.is_relative_to(Path(root).resolve())):
+        raise ValueError('Trusted adaptive root must be outside the deployment')
+    return path
+
+
+def revoke_monitor(root, laser_id, monitor_id, generation):
+    """Revoke only this monitor's grants. Owner restores independently of model."""
+    try:directory = control_root(root)/safe_id(laser_id)
+    except ValueError:return
+    grant_path=directory/'monitors'/(safe_id(monitor_id)+'.json')
+    grant=read_json(grant_path,{})
+    if isinstance(grant,dict) and grant.get('generation')==generation:
+        atomic_json(grant_path,{**grant,'enabled':False})
+    for path in directory.glob('*/background-control.json'):
+        value = read_json(path, {})
+        if isinstance(value,dict) and value.get('monitor_id') == monitor_id and value.get('generation') == generation:
+            atomic_json(path, {**value, 'enabled': False})
+
+
+def revoke_task(root, laser_id, task_id):
+    try:directory = control_root(root)/safe_id(laser_id)
+    except ValueError:return
+    for selector in directory.glob('*/adaptive-experiment.json'):
+        value = read_json(selector, {})
+        if not isinstance(value,dict) or value.get('id') != 'task-'+task_id:
+            continue
+        control = selector.parent/'background-control.json'
+        existing = read_json(control, {})
+        grant = value.get('background', {})
+        if isinstance(existing,dict) and isinstance(grant,dict) and all(existing.get(k) == grant.get(k) for k in ('monitor_id','generation')):
+            atomic_json(control, {**existing, 'enabled': False})
+
+
+CONTROLLERS = frozenset(('servo.ecdl_steady_lock','servo.native_current'))
+
+
+def _capabilities(operation='servo.ecdl_steady_lock',device=None):
+    from ldcon.core.adjustment_registry import capabilities
+    return capabilities(operation,device)
+
+
+def _adopted_capabilities(runtime, operation, laser):
+    """Runtime-adjustment capabilities of the profile the rig owner has ADOPTED now (2026-10-28).
+
+    The controller job's laser.yaml is the copy frozen at lock start; a live-adopted envelope change
+    (settings_adopt of background_adjustments.*) never reaches it. Read the owner's own report instead.
+    Older owners report only their device revision: the saved definition is used when its device digest
+    equals that revision (it then is the adopted device). Otherwise the parameter families are reported
+    unavailable with the reason (data validity), never from the stale copy.
+    """
+    rigs=[(k,v) for k,v in laser.get('devices',{}).items() if v.get('type')=='ecdl.rig.owner']
+    if operation!='servo.ecdl_steady_lock' or len(rigs)!=1:
+        return _capabilities(operation,rigs[0][1] if len(rigs)==1 else None)
+    key=rigs[0][0]
+    try:
+        described=owner_describe(laser)
+        reported=described.get('background_capabilities')
+        if isinstance(reported,dict) and isinstance(reported.get('supported_adjustments'),list):
+            return dict(reported,capability_source=dict(source='owner_adopted',revision=described.get('revision')))
+        from ldcon.core.interface_schema import digest
+        saved=runtime.interface_repository.read('lasers',laser['id'])['document']['devices'][key]
+        if digest(saved)!=described.get('revision'):
+            raise ValueError('Saved definition is not the owner-adopted device (adoption pending or refused)')
+        return dict(_capabilities(operation,saved),capability_source=dict(source='saved_equals_owner_adopted',revision=described['revision']))
+    except (OSError,ValueError,KeyError,TypeError,AttributeError) as error:
+        result=_capabilities(operation,None)
+        reason='Owner-adopted runtime envelope unavailable ('+type(error).__name__+'); no frozen copy is reported'
+        for item in result['parameter_adjustments'].values():item['reason']=reason
+        return dict(result,capability_source=dict(source='unavailable',reason=reason))
+
+
+def _live_status(status):
+    return bool(status.get('active') or status.get('state') in
+                ('idle','waiting_for_decision','measuring','waiting_for_measurement','waiting_recovery','awaiting_replan'))
+
+
+def route(runtime, task_id, data=None):
+    if data is not None and not isinstance(data, dict):
+        raise ValueError('Invalid background step')
+    from ldcon.core.interface_schema import load_mapping
+    task_dir = runtime.directory(safe_id(task_id))
+    task = runtime.get_job(task_id)
+    invocation = read_json(task_dir/'invocation.json')
+    params = invocation['parameters']
+    monitor_id = params.get('monitor_job_id')
+    if (params.get('instruction_profile') != 'adjustment'
+            or not any(c.get('operation',c.get('card'))=='agent.task' for c in task.get('cards',[]))):
+        raise ValueError('Task has no background adjustment grant')
+    laser_id = load_mapping((task_dir/'laser.yaml').read_text())['id']
+    manual=not monitor_id
+    if manual:
+        monitor_id='task-'+task_id
+        monitor=task
+    else:
+        monitor_dir = runtime.directory(safe_id(monitor_id))
+        monitor = runtime.get_job(monitor_id)
+        if (monitor.get('set_id') != task.get('set_id')
+                or load_mapping((monitor_dir/'laser.yaml').read_text())['id'] != laser_id
+                or not any(c.get('operation', c.get('card')) == 'agent.monitor' for c in monitor.get('cards', []))):
+            raise ValueError('Monitor grant belongs to another laser or operation')
+    root=control_root(runtime.root)
+    grant_path=root/safe_id(laser_id)/'monitors'/(safe_id(monitor_id)+'.json')
+    if any(path.is_symlink() for path in (grant_path,grant_path.parent,grant_path.parent.parent)):
+        raise ValueError('Trusted monitor grant must not be a symlink')
+    grant=read_json(grant_path,{})
+    if not isinstance(grant,dict):grant={}
+    if manual:
+        from ldcon.agents.manual_adjustment_grant import plan
+        from experiment_core.records import digest
+        expected=plan(task_dir,params)
+        if (grant.get('source')!='manual_task' or grant.get('task_id')!=task_id
+                or grant.get('bounds')!=expected or grant.get('parameters_hash')!=digest(expected)):
+            raise ValueError('Manual grant does not match the frozen approved plan')
+    updated=grant.get('last_seen');max_age=grant.get('max_age_s')
+    live_grant=bool(task.get('status')=='running' and monitor.get('status')=='running'
+        and grant.get('enabled') is True and isinstance(grant.get('bounds'),dict) and grant['bounds'].get('enabled') is True
+        and isinstance(grant.get('generation'),str) and grant['generation']
+        and isinstance(grant.get('parameters_hash'),str) and grant['parameters_hash']
+        and type(updated) in (int,float) and math.isfinite(updated)
+        and type(max_age) in (int,float) and math.isfinite(max_age) and 0<max_age<=180
+        and 0<=time.time()-updated<=max_age)
+    # Runtime parameter receipt, rather than editable model text, determines the
+    # enabled envelope. Physical range/step/slew validation remains in the owner.
+    bounds = grant.get('bounds',{})
+    jobs = runtime.active_jobs(set_id=task['set_id'])
+    controllers = [j for j in jobs if j.get('status') == 'running' and any(
+        c.get('operation', c.get('card')) in CONTROLLERS for c in j.get('cards', []))]
+    if len(controllers) != 1:
+        return dict(status='unavailable', reason='One running supported controller is required; no lock is started',
+                    supported_adjustments=[],unsupported_adjustments=['current','pi','slow_loop','feedforward'])
+    controller = controllers[0]
+    operation=next(c.get('operation',c.get('card')) for c in controller['cards']
+                   if c.get('operation',c.get('card')) in CONTROLLERS)
+    laser=load_mapping((runtime.directory(safe_id(controller['id']))/'laser.yaml').read_text())
+    if laser['id']!=laser_id:
+        raise ValueError('Controller belongs to another laser')
+    capabilities=_adopted_capabilities(runtime,operation,laser)
+    directory = root/safe_id(laser_id)/safe_id(controller['id'])
+    if directory.parent.is_symlink() or directory.is_symlink() or not directory.is_dir():
+        raise ValueError('Controller has not enabled the trusted adaptive manager')
+    selection_id = 'task-'+task_id
+    experiment = directory/'adaptive-experiments'/selection_id/'adaptive-window'
+    status = read_json(experiment/'status.json', {})
+    mode_laser=load_mapping((runtime.directory(safe_id(controller['id']))/'laser.yaml').read_text())
+    operating_mode=mode_read(mode_laser) if data is None or data.get('action')!='cancel' else None
+    if data is None:
+        from ldcon.agents.adjustment_guidance import current as current_guidance
+        guidance=current_guidance(runtime,laser_id)
+        results = sorted((experiment/'results').glob('*.json'), key=lambda p:p.stat().st_mtime)
+        latest = read_json(results[-1], {}) if results else None
+        return dict(status=status or dict(state='not_started'), latest_result=latest, operating_mode=operating_mode, adjustment_guidance=guidance,
+                    checkpoint=read_json(experiment/'checkpoint.json', {}),
+                    handoff=read_json(directory/'background-handoff.json',{}),
+                    controller_job_id=controller['id'],envelope=bounds,grant_active=live_grant,
+                    **capabilities)
+    if not isinstance(data, dict) or set(data)-{'action','request_id','value','based_on','family','pi_candidate','parameter_candidate','candidate','expected_operating_mode_revision'}:
+        raise ValueError('Invalid background step')
+    action = data.get('action')
+    safe_id(data.get('request_id'))
+    if action not in ('begin','measure_here','move_and_measure','adopt','cancel','replan'):
+        raise ValueError('Unsupported background step')
+    if 'family' in data and action!='begin':raise ValueError('Adjustment family is selected only at begin')
+    if 'candidate' in data and action!='replan':raise ValueError('A continuation candidate is valid only at replan')
+    if 'pi_candidate' in data and (action!='begin' or data.get('family')!='pi'):
+        raise ValueError('PI candidate is selected only at PI begin')
+    from ldcon.core.adjustment_registry import FAMILIES,PARAMETER_FAMILIES,parameters as trial_parameters
+    family=data.get('family','current')
+    if 'parameter_candidate' in data and (action!='begin' or family not in PARAMETER_FAMILIES):
+        raise ValueError('Runtime parameter candidate is selected only at slow-loop/feedforward begin')
+    if family not in FAMILIES:raise ValueError('Unsupported background adjustment family')
+    if action=='begin' and family not in capabilities['supported_adjustments']:
+        raise ValueError('This controller does not support the requested adjustment family')
+    if action=='begin' and params.get('adjustment_family','auto') not in ('auto',family):
+        raise ValueError('Adjustment family differs from this task selection')
+    if action in ('move_and_measure','adopt'):
+        if type(data.get('value')) not in (int,float) or not math.isfinite(data['value']):
+            raise ValueError('Current movement/adoption requires a finite numeric value')
+    elif 'value' in data:raise ValueError('This background action accepts no current value')
+    if action!='cancel' and not live_grant:
+        raise ValueError('Monitor/task grant is stopped, disabled or stale; no new background action')
+    if action!='cancel':
+        expected=data.get('expected_operating_mode_revision')
+        if type(expected) is not int or expected != mode_revision(operating_mode):
+            raise ValueError('Operating mode changed or is missing; refresh owner mode before planning')
+    descriptor=os.open(directory/'gateway.lock',os.O_CREAT|os.O_RDWR|os.O_NOFOLLOW,0o600)
+    with os.fdopen(descriptor,'a') as lock:
+        fcntl.flock(lock, fcntl.LOCK_EX)
+        selector_path = directory/'adaptive-experiment.json'
+        old = read_json(selector_path, {})
+        if old and old.get('id') != selection_id:
+            other = read_json(directory/'adaptive-experiments'/safe_id(old['id'])/'adaptive-window/status.json', {})
+            if not other or _live_status(other):
+                raise ValueError('Another adaptive task owns this controller')
+        if action == 'begin':
+            if family not in bounds.get('families',['current']):
+                raise ValueError('Adjustment family is outside this monitor grant')
+            selected=dict(id=selection_id,background=dict(monitor_id=monitor_id,generation=grant['generation'],
+                handoff_timeout_s=bounds['handoff_timeout_s'],grant_revision=grant['parameters_hash'],
+                expected_operating_mode_revision=data['expected_operating_mode_revision']))
+            if read_json(directory/'protocol.json',{}).get('continuation') is True:
+                selected['continuation']=True
+            if family=='pi':
+                from ldcon.jobs.background_pid_session import background_parameters
+                approved=bounds.get('pid_parameters',{})
+                p=background_parameters({'parameters':approved},
+                    {'candidate':data['pi_candidate']} if 'pi_candidate' in data else {},require_candidate=True)
+                if p['save_settings']:
+                    raise ValueError('Background PI requires explicit save_settings=false')
+                if p['strategy']=='validated_candidates' and operation not in ('servo.native_current','servo.ecdl_steady_lock'):
+                    raise ValueError('This controller does not support explicit PI candidates')
+                controller_ids={c.get('id',c.get('card_id')) for c in controller.get('cards',[]) if c.get('operation',c.get('card'))==operation}
+                if p['controller_card_id'] not in controller_ids:
+                    raise ValueError('Approved PI parameters name another controller card')
+                selected.update(family='pi',pid_parameters=p)
+            elif family in PARAMETER_FAMILIES:
+                plan=dict((bounds.get('adjustment_parameters') or {}).get(family,{}) or {})
+                if 'parameter_candidate' in data:plan['candidate']=data['parameter_candidate']
+                p=trial_parameters(plan,family,require_candidate=True)
+                selected.update(family=family,adjustment_parameters=p)
+            else:
+                selected.update(half_span_v=bounds['half_span_v'],timeout_s=bounds['timeout_s'],
+                                max_points=bounds['max_points'],require_dither=True)
+            if old and old.get('id') == selection_id:
+                if old != selected:raise ValueError('Background admission changed; do not replace an existing session')
+                control=read_json(directory/'background-control.json',{})
+                if not control.get('enabled') or not all(control.get(k)==selected['background'][k] for k in ('monitor_id','generation')):
+                    return dict(status='revoked',experiment_id=selection_id,message='This immutable session cannot be revived; create a new task')
+                if status and not _live_status(status):return dict(status='already_terminal',experiment_id=selection_id,experiment_status=status)
+                return dict(status='already_submitted', experiment_id=selection_id)
+            atomic_json(directory/'background-control.json', dict(enabled=True, monitor_id=monitor_id, generation=grant['generation']))
+            atomic_json(selector_path, selected)
+            return dict(status='submitted', experiment_id=selection_id, message='Await owner admission; no measurement yet')
+        if old.get('id') != selection_id or not (experiment/'inbox').is_dir():
+            raise ValueError('Background experiment is not admitted yet')
+        if old.get('background',{}).get('monitor_id')!=monitor_id:
+            raise ValueError('Experiment belongs to another monitor')
+        if action!='cancel' and old['background'].get('expected_operating_mode_revision')!=mode_revision(operating_mode):
+            raise ValueError('Operating mode changed after admission; cleanup remains available')
+        if old.get('family') in ('pi',*PARAMETER_FAMILIES) and action not in ('cancel','replan'):
+            raise ValueError('Parameter comparison runs autonomously; inspect status or cancel this admitted trial')
+        if status and not _live_status(status):
+            if action=='cancel':return dict(status='already_terminal',experiment_status=status)
+            raise ValueError('Background experiment is terminal; no late proposal may act')
+        control=read_json(directory/'background-control.json',{})
+        if action!='cancel' and (not control.get('enabled') or not all(
+                control.get(k)==old['background'].get(k)==({'monitor_id':monitor_id,'generation':grant['generation']})[k]
+                for k in ('monitor_id','generation')) or old['background'].get('grant_revision')!=grant['parameters_hash']):
+            raise ValueError('Background intervention generation was revoked')
+        command = dict(id=data['request_id'], action=action, based_on=data.get('based_on'))
+        if 'value' in data:command['value'] = data['value']
+        if action=='replan':
+            if old.get('continuation') is not True or status.get('state')!='awaiting_replan':
+                raise ValueError('Owner has not confirmed a recoverable continuation')
+            if 'candidate' in data:
+                if old.get('family')=='pi':
+                    from ldcon.jobs.background_pid_session import background_parameters
+                    checked=background_parameters({'parameters':bounds['pid_parameters']},{'candidate':data['candidate']},require_candidate=True)
+                elif old.get('family') in PARAMETER_FAMILIES:
+                    checked=trial_parameters({**bounds['adjustment_parameters'][old['family']],'candidate':data['candidate']},old['family'],require_candidate=True)
+                else:raise ValueError('Current replan requires a fresh baseline, not a candidate override')
+                command['candidate']=checked['candidate']
+        # Immutable ID, no command replay even after the worker claimed it.
+        for folder in ('inbox','claimed'):
+            previous = read_json(experiment/folder/(command['id']+'.json'))
+            if previous:
+                if previous != command:raise ValueError('Background command ID conflicts')
+                return dict(status='already_submitted', request_id=command['id'])
+        if action!='cancel' and (not isinstance(command['based_on'],str) or command['based_on'] != status.get('decision_revision')):
+            raise ValueError('Background decision evidence changed')
+        atomic_json(experiment/'inbox'/(command['id']+'.json'), command)
+        return dict(status='submitted', request_id=command['id'], message='Queued; inspect result and owner receipt')
+
+
+def call(box, name, args):
+    from ldcon.agents.agent_cards import _api
+    if box.context.get('task_scope') != 'background_adjustment':
+        raise ValueError('Only a bounded adjustment task may use this route')
+    tail = 'agent-tasks/'+box.meta['id']+'/background'
+    return _api(box, tail) if name == 'background_adjustment_status' else _api(box, tail, 'POST', args)
+
+
+def install_routes(app, prefix, body):
+    from fastapi import Request
+    @app.get(prefix+'/api/agent-tasks/{task_id}/background')
+    def status(task_id: str):return route(app.state.runtime, task_id)
+
+    @app.post(prefix+'/api/agent-tasks/{task_id}/background')
+    async def step(task_id: str, request: Request):return route(app.state.runtime, task_id, await body(request))

ldcon/agents/agent_bundle.py

@@ -0,0 +1,75 @@
+"""Installed English instruction sources and bounded reproducible task input."""
+import hashlib
+import json
+from pathlib import Path
+from ldcon.core.paths import resources_dir
+from experiment_core.agent_contracts import instruction_bundle
+from experiment_core.records import atomic_json, digest
+
+REVISION = '1.7'
+PROFILES = {'diagnosis', 'adjustment', 'research'}
+
+
+def build(directory, profile, *, context, evidence, max_input_bytes=32000):
+    if profile not in PROFILES:
+        raise ValueError('Unknown instruction profile')
+    resources = resources_dir() / 'agent_contract'
+    from ldcon.core.records import read_json
+    context = {**context, 'operating_mode_at_card_start':
+               read_json(Path(directory)/'operating-mode-at-start.json',
+                         dict(status='unavailable', reason='No owner observation recorded at card start'))}
+    from experiment_core.adjustment_guidance import instructions as guidance_instructions
+    context['adjustment_guidance_at_card_start']=read_json(
+        Path(directory)/'adjustment-guidance-at-start.json',
+        dict(availability='not_recorded',advisory_only=True))
+    from ldcon.agents.report_pdf import instructions as report_instructions
+    bundle = instruction_bundle((resources/'common.txt').read_bytes()+b'\n'+(resources/'response_optimization.txt').read_bytes()+b'\n'+guidance_instructions().encode()+b'\n'+report_instructions().encode(),
+        (resources/(profile+'.txt')).read_bytes(), revision=REVISION,
+        context=context, evidence=evidence, max_input_bytes=max_input_bytes)
+    bundle['instruction_profile'] = profile
+    bundle['bundle_revision'] = digest(bundle)
+    atomic_json(Path(directory)/'agent-bundle.json', bundle)
+    return bundle
+
+
+def turn_origin(directory, request_id, kind, *, active=True, task_id=None):
+    # The inbox wrapper is host-created. Its messages themselves still grant no
+    # physical authority; language selection is not authorization.
+    from ldcon.core.records import atomic_json
+    value = dict(request_id=request_id, kind=kind, active=active,
+                 job_id=Path(directory).name,
+                 origin='human' if kind in ('request', 'hub_inbox_watch') else 'automatic')
+    if task_id:
+        value['task_id'] = task_id
+    atomic_json(Path(directory)/'agent-current-request.json', value)
+
+
+def capability_probe(box, args):
+    """Local, non-actuating end-to-end MCP probe with an unpredictable challenge."""
+    from ldcon.core.records import read_json
+    from ldcon.agents.agent_tools import TOOLS
+    challenge = read_json(box.directory/'agent-probe-challenge.json', {})
+    if args.get('nonce') != challenge.get('nonce') or not challenge:
+        raise ValueError('Capability probe challenge changed')
+    manifest = read_json(box.directory/'agent-bundle.json', {})
+    if not manifest or manifest['bundle_revision'] != challenge['bundle_revision']:
+        raise ValueError('Capability probe bundle mismatch')
+    if digest({k:v for k,v in manifest.items() if k!='bundle_revision'})!=manifest['bundle_revision']:
+        raise ValueError('Capability probe bundle integrity mismatch')
+    if (hashlib.sha256(manifest['instructions'].encode()).hexdigest()!=manifest['instructions_sha256']
+            or digest(manifest['input'])!=manifest['input_sha256']):
+        raise ValueError('Capability probe content integrity mismatch')
+    if manifest['input']['context']['laser_id']!=box._laser_id:
+        raise ValueError('Capability probe laser mismatch')
+    names = {item['name'] for item in TOOLS}
+    allowed = box.context.get('task_allowed_tools')
+    if allowed is not None:
+        names &= set(allowed)
+    receipt = dict(nonce=challenge['nonce'], bundle_revision=manifest['bundle_revision'],
+                   laser_id=box._laser_id, tools=sorted(names),
+                   scoped_bundle_read=True, hardware_operations=0,
+                   probe_type='mcp_probe_invocation_and_scoped_manifest_read',
+                   tool_listing='enumerated', operation_permissions='not_probed',
+                   image_interpretation='not_probed')
+    atomic_json(box.directory/'agent-probe-receipt.json', receipt)
+    return receipt

ldcon/agents/agent_cards.py

@@ -0,0 +1,171 @@
+"""Same-laser card gateway; no raw instrument transport or API token exposure."""
+import json
+import re
+from urllib.request import Request,build_opener,ProxyHandler,HTTPRedirectHandler
+from urllib.error import HTTPError
+from ldcon.core.interface_schema import identifier,RETIRED_OPERATIONS,parameters
+from ldcon.core.records import read_json
+from ldcon.agents.failure_policy import sanitize
+
+# Laser-agent authority policy (2026-10-21): card operations and settings are
+# the agent's own work. Safety ranges are gated by the host approval ledger
+# (agent_authority), not by the Claude auto-mode classifier, so every scoped
+# MCP tool is preapproved. Put a tool name here to hand it back to native review.
+REVIEWED_TOOLS=frozenset()
+
+
+class NoRedirect(HTTPRedirectHandler):
+    def redirect_request(self,*args,**kwargs):
+        raise ValueError('Local card API must not redirect')
+
+
+def _api(box,tail,method='GET',payload=None):
+    server=read_json(box.root/'web-server.json',{})
+    port=server.get('port');prefix=server.get('path')
+    if (type(port) is not int or not 1<=port<=65535 or not isinstance(prefix,str)
+            or not re.fullmatch(r'/s/[A-Za-z0-9_-]{24,80}/',prefix)):
+        raise ValueError('Local dashboard is not configured')
+    request=Request('http://127.0.0.1:'+str(port)+prefix+'api/'+tail,
+        data=None if payload is None else json.dumps(payload,allow_nan=False).encode(),method=method,
+        headers={'Content-Type':'application/json','X-LDCon-Client':'web'})
+    try:
+        with build_opener(ProxyHandler({}),NoRedirect()).open(request,timeout=15) as response:
+            raw=response.read(2**20+1)
+            if len(raw)>2**20:raise ValueError('Card API response exceeds limit')
+            return json.loads(raw)
+    except HTTPError as error:
+        if error.code not in (400,403,404,409,422):raise
+        try:
+            rejected=json.loads(error.read(65536))
+            detail=rejected.get('detail','Card API rejected the request')
+            operation_error=rejected.get('operation_error')
+        except (ValueError,AttributeError):
+            detail='Card API rejected the request';operation_error=None
+        result=dict(status='rejected',http_status=error.code,reason=sanitize(detail))
+        if isinstance(operation_error,dict):result['operation_error']=sanitize(operation_error)
+        return result
+
+
+def _scope(box):
+    identifier(box.meta['set_id']);identifier(box.meta['deck_id'])
+    bundle=_api(box,'sets/'+box.meta['set_id'])
+    if bundle.get('status')=='rejected':return bundle,None
+    if bundle.get('laser_definition',{}).get('document',{}).get('id')!=box._laser_id:
+        raise ValueError('Current assignment belongs to another laser')
+    deck=next((d for d in bundle['deck_definitions'] if d['id']==box.meta['deck_id']),None)
+    if not deck:raise ValueError('Resident deck is no longer assigned')
+    return bundle,deck
+
+
+def _overrides(text):
+    if len(text.encode())>32768:raise ValueError('Card parameter override exceeds limit')
+    def reject(_):raise ValueError('Finite JSON required')
+    result=json.loads(text,parse_constant=reject)
+    if not isinstance(result,dict):raise ValueError('Card overrides must be a JSON mapping')
+    # JSON can parse 1e999 as infinity without calling parse_constant.
+    json.dumps(result,allow_nan=False)
+    return result
+
+
+
+def active_jobs(box):
+    """Same-laser discovery across assigned decks; never infer a device lease."""
+    value=_api(box,'jobs?active_only=true')
+    if value.get('status')=='rejected':return value
+    rows=[]
+    for job in value.get('jobs',[]):
+        if (job.get('set_id')!=box.meta['set_id'] or job.get('laser',{}).get('id')!=box._laser_id
+                or job.get('status') in ('failed','cancelled','interrupted','succeeded','completed','completed_with_failures')):
+            continue
+        rows.append(dict(job_id=job['id'],deck_id=job.get('deck_id'),status=job.get('status'),
+            controller_state=job.get('controller_state'),read_only=bool(job.get('read_only')),
+            blocks_new_control_card=not job.get('read_only',False),
+            cards=[dict(id=c.get('id'),operation=c.get('operation',c.get('card'))) for c in job.get('cards',[])],
+            created_utc=job.get('created_utc'),message=sanitize(job.get('message'))))
+    return dict(laser_id=box._laser_id,jobs=rows,
+        control_slot_blockers=[r['job_id'] for r in rows if r['blocks_new_control_card']],
+        evidence='Current dashboard job metadata, not an independent owner lease or physical lock verification. '
+                 'Use laser_card_job then laser_log_read for current readings. Never clear or stop an existing card solely because a duplicate start was rejected.')
+
+
+def call(box,name,args):
+    if name=='agent_work_capabilities':
+        return box.context.get('execution_profile',dict(status='unavailable',reason='Reconnect with a current work profile'))
+    bundle,deck=_scope(box)
+    if deck is None:return bundle
+    if name=='laser_active_jobs':return active_jobs(box)
+    if name=='laser_cards':
+        description=_api(box,'lasers/'+box._laser_id+'/operations')
+        if description.get('status')=='rejected':return description
+        capabilities={row['card_id']:row for row in description.get('cards',[])
+            if row.get('set_id')==box.meta['set_id'] and row.get('deck_id')==box.meta['deck_id']}
+        rows=[]
+        for card in deck['document']['cards']:
+            info=capabilities.get(card['id'],dict(runnable=False,
+                blocked_reasons=['Operation is not registered for this laser'],parameters={}))
+            rows.append(dict(id=card['id'],operation=card['operation'],retired=card['operation'] in RETIRED_OPERATIONS,
+                runnable=info['runnable'],blocked_reasons=sanitize(info.get('blocked_reasons',[])),
+                parameters=sanitize(info.get('parameters',{}))))
+        return dict(laser_id=box._laser_id,set_id=box.meta['set_id'],deck_id=box.meta['deck_id'],
+            expected_revision=bundle['revision'],cards=rows,
+            parameter_note='Displayed parameters may be redacted. Supply only explicit overrides; defaults remain in the backend.',
+            execution_note='Hourly monitoring is read-only; separately authorized card work uses native permission review and existing owners.')
+    if name in ('laser_card_job','laser_card_stop'):
+        if not re.fullmatch('[0-9a-f]{32}',args['job_id']):raise ValueError('Expected a job ID, not a path')
+        job=_api(box,'jobs/'+args['job_id'])
+        if job.get('status')=='rejected':return job
+        if (job.get('set_id')!=box.meta['set_id'] or job.get('laser',{}).get('id')!=box._laser_id):
+            raise ValueError('Job belongs to another laser/deck')
+        if name=='laser_card_stop':
+            reference=args['human_confirmation'].strip()
+            if not reference or len(reference)>2000:raise ValueError('Record the actual human stop/switch request reference')
+            if job['id']==box.meta['id']:raise ValueError('Do not stop your own resident transport; use the dashboard for resident replacement')
+            def stop():
+                result=_api(box,'jobs/'+job['id']+'/stop','POST',{})
+                if result.get('status')=='rejected':return result
+                return dict(status='stop_requested',job_id=job['id'],job_status=result.get('status'),
+                    stop_reconciliation=sanitize(result.get('stop_reconciliation')),
+                    human_confirmation=sanitize(reference),
+                    note='Poll laser_card_job until terminal. For an orphan operating-point proxy, inspect stop_reconciliation for the correlated parent/queue and independent owner proof; unknown prior effects remain unknown. For a stopped lock, use laser_stop_verify. Never kill, clear holds or infer physical state from pre-stop readings.')
+            return box.once(name,args,stop)
+        return dict(id=job['id'],status=job['status'],controller_state=job.get('controller_state'),
+            stop_reconciliation=sanitize(job.get('stop_reconciliation')),
+            message=sanitize(job.get('message')),online_tuning=sanitize(job.get('online_tuning',{})),
+            summary=sanitize(job.get('summary',{})),readings=sanitize(job.get('readings',{})),
+            cards=[dict(id=c.get('id'),operation=c.get('operation',c.get('card'))) for c in job.get('cards',[])],
+            evidence='Recorded dashboard state; use laser_log_read for details. Not independent hardware verification.')
+    identifier(args['card_id'])
+    card=next((c for c in deck['document']['cards'] if c['id']==args['card_id']),None)
+    if not card or card['operation'] in RETIRED_OPERATIONS:raise ValueError('Select a current card in this laser deck')
+    if card['operation'] in ('agent.resident','agent.log_watch','agent.request','notify.teams'):
+        raise ValueError('Use the dedicated resident/notification tools; no recursive agent launch')
+    if args['expected_revision']!=bundle['revision']:
+        return dict(status='rejected',reason='Assignment changed; refresh laser_cards and validate again')
+    overrides=_overrides(args.get('parameters_json','{}'))
+    # Validate locally before any HTTP mutation, with current assignment defaults.
+    p=parameters(card,{**deck.get('invocation_parameters',{}).get(card['id'],{}),**overrides})
+    route=f"sets/{box.meta['set_id']}/decks/{box.meta['deck_id']}"
+    payload=dict(parameters=overrides,expected_revision=bundle['revision'])
+    if name=='laser_card_validate':
+        result=_api(box,route+'/cards/'+card['id']+'/validate','POST',payload)
+        return dict(status='rejected' if result.get('status')=='rejected' else 'validated',
+            runnable=result.get('runnable',False),reason=result.get('reason'),
+            blocked_reasons=sanitize(result.get('blocked_reasons',[])),
+            parameters=sanitize(result.get('parameters',p)),expected_revision=bundle['revision'],
+            operation_error=sanitize(result.get('operation_error')))
+    if name!='laser_card_start':raise ValueError('Unknown card tool')
+    reference=args.get('human_confirmation','').strip()
+    if not reference or len(reference)>2000:raise ValueError('Record the actual human request/confirmation reference')
+    def start():
+        # No automatic stop, service restart, lease takeover or hold release.
+        result=_api(box,route+'/start','POST',dict(payload,card_id=card['id']))
+        if result.get('status')=='rejected':
+            if result.get('http_status')==409:
+                try:result=dict(result,active_jobs=active_jobs(box))
+                except (OSError,ValueError):result=dict(result,active_jobs=dict(status='unavailable'))
+            return result
+        return dict(status='submitted',job_id=result['id'],card_id=card['id'],
+            job_status=result.get('status'),online_tuning=sanitize(result.get('online_tuning',{})),
+            operation_request_id=result.get('operation_request_id'),
+            human_confirmation=sanitize(reference),note='Accepted by card system; not proof of completion. Inspect laser_card_job.')
+    return box.once(name,args,start)

ldcon/agents/agent_config_access.py

@@ -0,0 +1,22 @@
+"""Read grants for shared code and assigned configuration; never grants edits."""
+from pathlib import Path
+
+
+SHARED_CODE_INSTRUCTIONS = ('Read the actual installed shared source before implementation: '
+    'Use the configured immutable source roots and their installed version metadata. '
+    'Distinguish the current card release from older pinned owner code. State the exact path/version '
+    'and functions inspected. Subagent reports do not replace direct source verification. '
+    'These are Read grants only; never edit a shared immutable release, bypass a denied tool, '
+    'or treat source access as permission to change hardware or safety limits.')
+
+
+def read_rules(parameters):
+    from ldcon.core.site_bindings import shared_roots
+    rules = ['Read(/' + str(root) + '/**)' for root in shared_roots()]
+    for name in parameters.get('config_read_paths', []):
+        path = Path(name)
+        # Claude permission syntax treats these characters as patterns/separators.
+        if not path.is_absolute() or '..' in path.parts or any(c in str(path) for c in '*?[](),\n\r'):
+            raise ValueError('Expected a literal absolute configuration path')
+        rules.append('Read(/' + str(path) + ')')
+    return rules